Skip to content
Kindgi

Export a signed audit bundle for a decided approval

POST
/v1/approvals/{approvalId}/audit-bundle
curl --request POST \
  --url https://example.com/v1/approvals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/audit-bundle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "signingKeyId": "example", "includeMessages": false }'

Canonicalizes the approval + decision + evidence as sorted-key JSON and signs with the deployment’s Ed25519 key looked up by signingKeyId. Envelope shape mirrors provenance.export byte-for-byte so SDK clients can reuse a single verifyEd25519 wrapper for both. Only meaningful post-decision — pending approvals return 409 approval-not-decided.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
approvalId
required
string format: uuid

ApprovalId — opaque branded string (a UUID).

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Body for POST /v1/approvals/{approvalId}/audit-bundle. signingKeyId selects the Ed25519 key from the deployment’s signingKey binding. includeMessages optionally hydrates conversation messages tied to the approval’s run.

object
signingKeyId
required

The SigningKeyId the deployment plugs into its signingKey binding. Server looks up the private key via signingKey.getPrivateKey(signingKeyId) — 404 if unknown.

string
>= 1 characters
includeMessages

When true, hydrates conversation messages tied to the approval’s run (agent turns pin runId === conversationId). Empty array for non-agent runs — field always present when requested.

boolean

Responses

Section titled “Responses”

200

Section titled “200”

Signed audit bundle.

Media typeapplication/json

Signed exportable audit bundle. Same envelope shape as ExportProvenanceResult — clients can reuse the same verifyEd25519 wrapper for both. bundle is base64 of the exact bytes that were signed (sorted-key canonical JSON, no whitespace). Bundle body: { bundleVersion, approvalId, tenantId, subjectKind, subjectRef, requiredRole, status, decision, decidedAt?, evidence: { guardrailResults?, messages? }, createdAt, exportedAt }.

object
approvalId
required
string format: uuid
bundle
required

Base64-encoded canonical JSON of the bundle body.

string
bundleSchemaVersion
required

Integer schema version for the bundle body shape. Currently 1.

integer
algorithm
required
string
Allowed value: ed25519
signingKeyId
required
string
signature
required

Base64-encoded Ed25519 signature over bundle (after base64-decode).

string
publicKey
required

PEM-encoded Ed25519 public key (DER SPKI envelope). Pass into parsePublicKeyPem for verification.

string
canonicalization
required

Canonicalization algorithm — sorted-key JSON, no whitespace. Same algorithm as canonicalize.

string
Allowed value: sorted-key-json
exportedAt
required
string format: date-time
Example
{
  "algorithm": "ed25519",
  "canonicalization": "sorted-key-json"
}

400

Section titled “400”

Malformed request body.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Section titled “403”

Token lacks a reviewer role.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

Approval not found, signing key id unknown, or signing not configured on this deployment.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

Idempotency-Key was reused with a different body, or resource-state conflict.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}