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

# Replay a recorded policy version 2 decision from its evidence

> Re-runs the recorded decision and reports whether it reproduces.



## OpenAPI

````yaml openapi.bundled.yaml GET /v2/evidence/{recordId}/replay
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/evidence/{recordId}/replay:
    get:
      tags:
        - Policy v2 (experimental)
      summary: Replay a recorded policy version 2 decision from its evidence
      description: >-
        Re-runs the recorded decision and reports whether it reproduces. The
        caller must hold a register role. The replay changes nothing.
      operationId: policyV2Replay
      parameters:
        - name: recordId
          in: path
          required: true
          description: >-
            The evidence record id returned as `recordId` by `POST
            /v2/decisions`.
          schema:
            type: string
      responses:
        '200':
          description: The replay result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyV2ReplayResult'
              example:
                reproduced: true
                differences: []
                replayed:
                  outcome: APPROVE
        '401':
          $ref: '#/components/responses/PolicyV2Unauthenticated'
        '403':
          $ref: '#/components/responses/PolicyV2Forbidden'
        '404':
          $ref: '#/components/responses/PolicyV2NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            # EXPERIMENTAL Policy version 2. Available only where the deployment
            enables it.

            # Replay a recorded decision

            curl
            "https://parmana-api-real.vercel.app/v2/evidence/record-123/replay"
            \
              -H "Authorization: Bearer $PARMANA_API_KEY"
        - lang: typescript
          label: TypeScript
          source: >-
            // EXPERIMENTAL Policy version 2. Available only where the
            deployment enables it.

            // Replay a recorded decision

            const response = await fetch(
              "https://parmana-api-real.vercel.app/v2/evidence/record-123/replay",
              {
                method: "GET",
                headers: { Authorization: `Bearer ${process.env.PARMANA_API_KEY}` },
              },
            );

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

            # Replay a recorded decision

            import os

            import urllib.request



            def main() -> None:
                request = urllib.request.Request(
                    "https://parmana-api-real.vercel.app/v2/evidence/record-123/replay",
                    data=None,
                    method="GET",
                    headers={
                        "Authorization": "Bearer " + os.environ.get("PARMANA_API_KEY", ""),
                    },
                )
                with urllib.request.urlopen(request) as response:
                    print(response.status, response.read().decode("utf-8"))


            if __name__ == "__main__":
                main()
components:
  schemas:
    PolicyV2ReplayResult:
      type: object
      required:
        - reproduced
        - differences
      properties:
        reproduced:
          type: boolean
          description: True when the replay gives the same outcome and inputs.
        differences:
          type: array
          items:
            type: string
        replayed:
          type: object
          additionalProperties: true
          description: The decision the replay produced, in the evidence record's fields.
    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
    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:
    PolicyV2Unauthenticated:
      description: No key, or an unknown key (EXPERIMENTAL Policy v2 route).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyV2Error'
          example:
            error: unauthenticated
    PolicyV2Forbidden:
      description: >-
        The caller's role does not allow this change or screen (EXPERIMENTAL
        Policy v2 route).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyV2Error'
          example:
            error: forbidden
            message: The caller does not hold a role that allows this change.
    PolicyV2NotFound:
      description: No such item for this caller (EXPERIMENTAL Policy v2 route).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PolicyV2Error'
          example:
            error: not_found
    RateLimited:
      description: >-
        Too many requests from this caller on this route in the last minute. The
        default limits are 30 per caller per minute on `/execute`, 300 per IP
        address on `/health` and `/ready`, and 60 per IP address shared by the
        unauthenticated verification and handbook routes. The request never
        reached the handler, so nothing was recorded or executed. Wait the
        number of seconds in the `Retry-After` header, then retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.schema'
          examples:
            rateLimited:
              summary: Rate limit exceeded
              value:
                error: Rate limit exceeded. Try again later.
                code: RATE_LIMITED
  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.