Skip to content
Kindgi

Export a signed provenance bundle for a run

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

Signs the run’s provenance (and, when asked, its messages) with the deployment’s export key, and records the export (an export-signed audit event). The same envelope as the other signed exports; check publicKey against GET /v1/export-signing-keys. A deployment with no export key answers 404 signing-not-configured.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

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

RunId — opaque branded string (a UUID).

Header Parameters

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

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Body

Section titled “Request Body”
Media typeapplication/json

Optional: no body signs with the active key.

object
signingKeyId

Optional: sign with this key, one of GET /v1/export-signing-keys. Leave it out to sign with the deployment’s active key. A key the deployment doesn’t sign with is 404 signing-key-not-found.

string
>= 1 characters
includeMessages

When true, hydrates conversation messages tied to the run (agent turns pin runId === conversationId). Non-agent runs return an empty messages: [] — the field is still present on the bundle for shape stability.

boolean

Responses

Section titled “Responses”

200

Section titled “200”

Signed bundle.

Media typeapplication/json

A run’s signed provenance. Body: { bundleSchemaVersion, provenanceId, runId, tenantId, version, createdAt, flowRef?, dag: { nodes, edges }, messages?, callUsage?, exportedAt }; callUsage is each model call’s usage from the cost ledger, as it stood when signed.

object
runId
required
string format: uuid
kind

Which export this is: audit-bundle, provenance or compliance. Absent from older servers.

string
Allowed value: provenance
bundle
required

Base64 of the exact bytes that were signed: the body, as sorted-key JSON with no whitespace. Verify these bytes; nothing needs re-serializing.

string
bundleSchemaVersion
required

The body’s version, semver. 1.2.0 adds exportedAt to the signed body; 1.1.0 added callUsage.

string
algorithm
required

The signing key’s algorithm. ecdsa-p256-sha256 signatures are IEEE P1363 r‖s. A verifier refuses an algorithm it doesn’t know.

string
Allowed values: ed25519 ecdsa-p256-sha256
signingKeyId
required

The key that signed it: one of GET /v1/export-signing-keys.

string
signature
required

Base64 of the 64-byte signature over the bundle bytes: Ed25519’s, or ECDSA P-256’s as IEEE P1363 r‖s.

string
publicKey
required

The signing key’s public half, PEM SPKI. On its own it only proves the bytes weren’t changed; check it against GET /v1/export-signing-keys (or a key you pinned) to know who signed them.

string
canonicalization
required

Sorted-key JSON, no whitespace (canonicalize in @kindgi/schema).

string
Allowed value: sorted-key-json
exportedAt
required

When it was signed: the same instant as the signed body’s exportedAt.

string format: date-time
Example
{
  "kind": "provenance",
  "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"
  }
}

404

Section titled “404”

Provenance 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"
  }
}

413

Section titled “413”

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

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"
  }
}

See also