> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive delivery events for approval notifications

> Receives delivery events for policy version 2 notifications.



## OpenAPI

````yaml openapi.bundled.yaml POST /v2/notifications/events
openapi: 3.1.0
info:
  title: Parmana API
  version: 1.0.0
  description: >
    Parmana sits between an AI agent and the systems it acts on. An agent sends
    a Business Transaction: who

    authorized it, what action it wants, and the facts that justify it. Parmana
    evaluates the policy bound to

    the action, checks any signed human approval the policy requires, releases
    the action to the connector

    only if the policy approves, and returns a signed Execution Trust Record
    anyone can verify.


    **Authentication.** Send `Authorization: Bearer <key>` on every request. The
    only routes that need no key

    are the probes, the documents and the independent verification routes: `GET
    /health`, `GET /ready`,

    `GET /openapi.yaml`, `GET /openapi.json`, `GET /api-manifest.json`, `GET
    /documentation`,

    `GET /reference`, `GET /parmana-handbook.pdf`, `GET
    /handbook/download-leads`,

    `POST /handbook/download-leads`, `POST /refusal/verify`, `POST
    /execution-intents/verify`,

    `POST /audit/verify`, `GET /keys/{keyId}` and `GET /.well-known/jwks.json`.
    A missing or unknown key

    returns `401` before anything else runs. The server holds only a hash of
    each key. See

    [Authentication](/api-reference/authentication).


    **Two kinds of key.** An agent or service key may invoke only the
    capabilities listed on it. A human key

    (`credentialHolderType: USER`) is required for governance: proposing and
    approving policies, approvers

    and external connectors, and repairing Execution Intents. Approving or
    rejecting a change also needs a

    step up authorization signed with the checker's own step up key, and the
    checker must not be the

    person who proposed it.


    **Ownership.** Every lookup by `businessTransactionId` is scoped to the key
    that submitted the

    transaction. A transaction submitted by another key returns the same `404`
    as one that does not exist.


    **Try it live.** The "Try it" panels call production,
    `https://parmana-api-real.vercel.app`, with whatever key

    you enter. There is no public sandbox yet, so do not send test data through
    these panels.


    **Start here:** the [Quickstart](/quickstart), then [Integrate
    Parmana](/agents/integrate) for agents

    and [Connect any external system](/guides/connect-any-external-system) for
    your own endpoint.
  contact:
    name: Parmana Systems
    email: founder@parmanasystems.com
  license:
    name: Apache License 2.0, see LICENSE
    url: https://docs.parmanasystems.com/license
servers:
  - url: https://parmana-api-real.vercel.app
    description: Production. Needs a key issued by the operator.
  - url: http://localhost:3000
    description: Local (packages/api, PORT env var, default 3000)
security:
  - bearerAuth: []
tags:
  - name: Execution
    description: >-
      Executes a Business Transaction through the complete Execution Trust
      pipeline
  - name: Transactions
    description: Business Transaction creation and retrieval
  - name: Verification
    description: Deterministic verification of an Execution Trust Record
  - name: Receipts
    description: Cryptographically signed Execution Trust Receipts
  - name: Trust Records
    description: Execution Trust Record retrieval
  - name: Replay
    description: Deterministic replay of a recorded Execution Trust Record
  - name: Policies
    description: Policy existence/readability check
  - name: Policy Governance
    description: Maker-checker proposal, listing, approval, and rejection of policy changes
  - name: Approvers
    description: Maker-checker for the keys trusted to sign approvals, without a deploy
  - name: External Connectors
    description: >-
      Maker-checker for binding a capability to an operator's HTTPS endpoint and
      its policy, without a deploy (ADR-0013)
  - name: Policy v2 (experimental)
    description: >-
      EXPERIMENTAL. Policy version 2 decisions, reviews, the register, console
      and notification endpoints. Mounted only when the deployment enables
      policy version 2. Shapes may change in a minor release until promoted.
  - name: Business Signal Sources
    description: >-
      Maker-checker for the business systems Parmana asks for the facts a policy
      needs, without a deploy (RFC-0023)
  - name: Authority Grants
    description: >-
      Maker-checker for which agent may have which action decided, within which
      limits, until when (RFC-0023)
  - name: Sandbox
    description: Routes that exist only in sandbox mode, not on production
  - name: Kill Switch
    description: >-
      Operator kill switch (ADR-0017). Trip and reset need the operator
      capabilities, and probe results need the probe capability; status is open
      to any authenticated caller
  - name: Refusal Records
    description: >-
      Durable, signed evidence that a policy decision rejected a transaction
      (RFC-0021)
  - name: Execution Intents
    description: >-
      A signed statement, stored before an action is released, of exactly what
      is about to be released, plus the operator tools to find and repair a
      released action that has no signed Trust Record (ADR-0012)
  - name: Audit
    description: >-
      Signed caller-authentication audit events, independently
      third-party-verifiable
  - name: System
    description: Operational endpoints
paths:
  /v2/notifications/events:
    post:
      tags:
        - Policy v2 (experimental)
      summary: Receive delivery events for approval notifications
      description: >-
        Receives delivery events for policy version 2 notifications. The events
        are verified with the events secret, or refused with `403 not_verified`.
        Not called by clients.
      operationId: policyV2NotificationEvents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                additionalProperties: true
      responses:
        '200':
          description: The number of events recorded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - recorded
                properties:
                  recorded:
                    type: integer
                    minimum: 0
              example:
                recorded: 1
        '400':
          $ref: '#/components/responses/PolicyV2InvalidRequest'
        '403':
          description: The events did not verify.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyV2Error'
              example:
                error: not_verified
      security: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            # EXPERIMENTAL Policy version 2. Available only where the deployment
            enables it.

            # Delivery events; clients do not call it

            curl -X POST
            "https://parmana-api-real.vercel.app/v2/notifications/events" \
              -H "Content-Type: application/json" \
              -d '[{"type":"Delivery"}]'
        - lang: typescript
          label: TypeScript
          source: >-
            // EXPERIMENTAL Policy version 2. Available only where the
            deployment enables it.

            // Delivery events; clients do not call it

            const response = await fetch(
              "https://parmana-api-real.vercel.app/v2/notifications/events",
              {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify([{ type: "Delivery" }]),
              },
            );

            console.log(response.status, await response.text());
        - lang: python
          label: Python
          source: >-
            # EXPERIMENTAL Policy version 2. Available only where the deployment
            enables it.

            # Delivery events; clients do not call it

            import json

            import urllib.request


            BODY = r'[{"type":"Delivery"}]'



            def main() -> None:
                request = urllib.request.Request(
                    "https://parmana-api-real.vercel.app/v2/notifications/events",
                    data=json.dumps(json.loads(BODY)).encode("utf-8"),
                    method="POST",
                    headers={
                        "Content-Type": "application/json",
                    },
                )
                with urllib.request.urlopen(request) as response:
                    print(response.status, response.read().decode("utf-8"))


            if __name__ == "__main__":
                main()
components:
  responses:
    PolicyV2InvalidRequest:
      description: >-
        The body or a parameter is not valid. The message names the field
        (EXPERIMENTAL Policy v2 route).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyV2Error'
          example:
            error: invalid_request
            message: capability must look like namespace:verb.
  schemas:
    PolicyV2Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            A stable machine code, for example forbidden, refused,
            invalid_request, conflict, not_found, not_enabled, not_verified, or
            unauthenticated.
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Caller API key issued by scripts/generate-api-key.ts. Sent as
        Authorization: Bearer <key>. Verified against a stored SHA-256 hash in
        constant time by packages/api/src/auth/StaticKeyAuthenticator.ts.
        Required on every route not listed as exempt in this document's
        top-level description. See /api-reference/authentication.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.