> ## 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.

# Get the status of a Business Transaction

> Returns the current status event of a Business Transaction.



## OpenAPI

````yaml openapi.bundled.yaml GET /transactions/{businessTransactionId}/status
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: 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:
  /transactions/{businessTransactionId}/status:
    get:
      tags:
        - Transactions
      summary: Get the status of a Business Transaction
      description: >
        Returns the current status event of a Business Transaction. With
        `?history=true`, returns every

        status event in order, oldest first. Each event has a `sequence`, its
        `stage` (declare, decide,

        sign, execute, verify or reconcile), `occurredAt`, and a `reason` where
        one was recorded.

        Transactions declared before status events existed have one `RECEIVED`
        event marked `legacy: true`.
      operationId: getTransactionStatus
      parameters:
        - name: businessTransactionId
          in: path
          required: true
          description: The businessTransactionId the transaction was declared with.
          schema:
            type: string
            format: uuid
        - name: history
          in: query
          required: false
          description: Set to true to include the full status history.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
      responses:
        '200':
          description: The current status, and the history when requested.
          content:
            application/json:
              schema:
                type: object
                required:
                  - businessTransactionId
                  - current
                properties:
                  businessTransactionId:
                    type: string
                  current:
                    $ref: '#/components/schemas/TransactionStatusEvent'
                  history:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionStatusEvent'
              example:
                businessTransactionId: 9b2c4f1e-3d7a-4e8b-9f10-2a6c5d7e8f90
                current:
                  eventId: 0c5f7a2e-8d41-4b6a-9e3c-1f2a7b8c9d01
                  businessTransactionId: 9b2c4f1e-3d7a-4e8b-9f10-2a6c5d7e8f90
                  sequence: 6
                  status: VERIFIED
                  stage: verify
                  occurredAt: '2026-11-15T10:00:02.000Z'
                  legacy: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: >-
            No Business Transaction with this id was declared by this caller, or
            no status is recorded for it.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Business Transaction not found.
                code: NOT_FOUND
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            # Reads the status of a declared Business Transaction, with its full
            history.

            # Replace the id with the businessTransactionId you declared.

            TXN_ID="6f6582a1-4e1a-4800-a73b-cb4c3aa32110"

            curl
            "https://parmana-api-real.vercel.app/transactions/$TXN_ID/status?history=true"
            \
              --silent \
              -H "Authorization: Bearer $PARMANA_API_KEY"
        - lang: typescript
          label: TypeScript
          source: |-
            import { ParmanaClient } from "@parmana/sdk";

            const client = new ParmanaClient({
              endpoint: "https://parmana-api-real.vercel.app",
              apiKey: process.env.PARMANA_API_KEY!,
            });

            // Replace the id with the businessTransactionId you declared.
            const status = await client.transactionStatus(
              "6f6582a1-4e1a-4800-a73b-cb4c3aa32110",
              { history: true },
            );

            console.log(status.current.status, status.current.stage);

            for (const event of status.history ?? []) {
              console.log(event.sequence, event.status, event.stage, event.occurredAt);
            }
        - lang: python
          label: Python
          source: |-
            import os

            from parmana import ParmanaClient

            client = ParmanaClient(
                endpoint="https://parmana-api-real.vercel.app",
                api_key=os.environ["PARMANA_API_KEY"],
            )

            # Replace the id with the businessTransactionId you declared.
            status = client.transaction_status(
                "6f6582a1-4e1a-4800-a73b-cb4c3aa32110",
                history=True,
            )

            print(status.current.status, status.current.stage)

            for event in status.history or []:
                print(event.sequence, event.status, event.stage, event.occurred_at)
components:
  schemas:
    TransactionStatusEvent:
      type: object
      description: One append-only status event of a Business Transaction (decision D23).
      required:
        - eventId
        - businessTransactionId
        - sequence
        - status
        - stage
        - occurredAt
        - legacy
      properties:
        eventId:
          type: string
          format: uuid
        businessTransactionId:
          type: string
        sequence:
          type: integer
          minimum: 1
          description: Position in the transaction's history, starting at 1.
        status:
          type: string
          enum:
            - RECEIVED
            - POLICY_EVALUATED
            - APPROVED
            - REJECTED
            - EXECUTING
            - EXECUTED
            - FAILED
            - VERIFIED
        stage:
          type: string
          enum:
            - declare
            - decide
            - sign
            - execute
            - verify
            - reconcile
        occurredAt:
          type: string
          format: date-time
        recordRef:
          type: string
          description: The authorization the event refers to, where there is one.
        reason:
          type: string
          description: Why the status is FAILED, REJECTED or a reconciliation outcome.
        legacy:
          type: boolean
          description: >-
            True for the one RECEIVED event written for a transaction declared
            before status events existed. Its later status is not derived, so it
            is not a fully traced history.
    error.schema:
      title: Error Response
      description: >-
        Shared error envelope produced by
        packages/api/src/middleware/error-handler.ts and by every route's inline
        validation checks. error is always a plain human-readable string (never
        a nested object). code is present only when the failure was a
        RuntimeError subclass reaching the centralized error handler
        (VerificationFailedError, ReceiptGenerationError, or an uncategorized
        RuntimeError); it is absent from every inline route-level check
        (businessTransactionId format/required checks) and from
        BusinessTransactionValidationError, PolicyValidationError,
        SignalValidationError, PolicyNotFoundError,
        DuplicateBusinessTransactionError, and the generic 500 fallback. POST
        /policies/validate does NOT use this envelope at all. See its own
        response schema. For the triggering condition and recommended caller
        action behind any specific error/code/status combination, see the Error
        catalog at /api-reference/error-catalog.
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: >-
            Stable machine-readable error code. Only present for errors that
            reach the handler as a RuntimeError.
          examples:
            - RUNTIME_ERROR
            - VERIFICATION_FAILED
            - RECEIPT_GENERATION_FAILED
            - POLICY_DENIED
            - CAPABILITY_NOT_ALLOWED
            - RATE_LIMITED
            - AUDIT_UNAVAILABLE
            - SIGNING_UNAVAILABLE
            - CONNECTOR_NOT_REGISTERED
            - EXECUTION_RECORD_INCOMPLETE
            - EXECUTION_INTENT_UNAVAILABLE
            - EXECUTION_INTENT_RESULT_NOT_RECORDED
            - EXECUTION_INTENT_NOT_FOUND
            - EXECUTION_INTENTS_NOT_ENABLED
            - EXECUTION_INTENT_NOT_RESOLVABLE
            - EXECUTION_INTENT_RESOLUTION_INVALID
            - NON_HUMAN_CALLER_DENIED
            - EXECUTION_OUTCOME_UNKNOWN
            - AUTHORIZATION_NO_LONGER_VALID
        executionStatus:
          type: string
          enum:
            - EXECUTION_UNKNOWN
            - NOT_EXECUTED
          description: >-
            RFC-0023 phase 4. EXECUTION_UNKNOWN with EXECUTION_OUTCOME_UNKNOWN:
            the action was released and the call failed, so whether it ran is
            unknown; never reported as failed, and the Execution Intent stays
            ERRORED until a person resolves it. NOT_EXECUTED with
            AUTHORIZATION_NO_LONGER_VALID: the release was refused because a
            business condition or the authority grant it rested on no longer
            held, and nothing was sent.
      examples:
        - error: businessTransactionId must be a valid UUID.
        - error: >-
            Business Transaction 'eed2a972-1bf5-4166-8472-761f76fbf1b2' already
            exists.
        - error: >-
            Execution rejected: Vendor payment rejected because the assessed
            payment risk exceeds the maximum permitted threshold.
          code: RUNTIME_ERROR
  responses:
    Unauthorized:
      description: >-
        The `Authorization` header is missing, is not a bearer key, or names a
        key the server does not know. Nothing ran. Send a valid key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.schema'
          examples:
            authRequired:
              summary: Real captured response, missing or invalid Authorization header
              value:
                error: authentication required
  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.