Managed API reference

The Managed API runs the same stable operations as the local packages, SDK, CLI and MCP server. Free-trial workspaces and active Platform and Enterprise workspaces get it at https://runstamp.com/api/v2.

Authentication boundaries

Local packages and the local MCP server need no account or API key. Never put a pj_live_ key in browser code.

Execution flow

1. Submit an operation with an Idempotency-Key.
2. Poll the returned status_url until it reaches a terminal state.
3. Read result_url. Large successful results redirect to immutable private storage.

curl -fsS -X POST \
  -H "Authorization: Bearer $RUNSTAMP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: validate-invoice-42" \
  https://runstamp.com/api/v2/operations/pdf/validate \
  --data '{"input":"BASE64_PDF","options":{}}'

For a document operation, input is the file as a standard base64 string. The route also accepts {"bytes":"BASE64_PDF"} and {"$runstampBinary":"base64","data":"BASE64_PDF"}, the envelopes the SDK's managed transport sends. Invalid base64 is rejected with common/SCHEMA_REJECTED, naming the field.

To name the run in the console, send the customer's file name in the optional Runstamp-Document-Name header. Percent-encode non-ASCII characters, for example Runstamp-Document-Name: Q3%20budget.xlsx. Without it, the console uses the document's title or first line. The name is for display only and does not affect idempotency.

A run blocked before the operation executes, such as by environment policy, still returns 200 from result_url, with ok: false and the blocking error code and message.

An exact idempotent replay returns the existing execution. Reusing a key with different content returns 409. Inline REST bodies are capped at 4 MiB (4,194,304 bytes) of raw request body on hosted Runstamp and 10 MiB (10,485,760 bytes) when you self-host. On hosted Runstamp a base64 document must be under roughly 3 MiB before encoding; larger bodies return 413 ERR_PAYLOAD_TOO_LARGE. The SDK switches transport automatically at 768 KiB. For staged input and redirects up to 192 MiB, see Large inputs and results.

Endpoints

These tables index the endpoints. They are not a second schema. For parameters, status codes and response schemas, open the Hosted V2 OpenAPI contract.

Discovery and execution

Governed review and release

These routes use the signed-in customer session. They bind decisions to exact artifact evidence.

Render compatibility request

New integrations should use operation routes. The render route stays for protocol-v2 presentation clients. It always runs durably, even when mode is sync.

Canonical render request:

{
  "format": "pptx",
  "sourceSchema": "protocol_v2",
  "document": {
    "version": "2.0",
    "title": "Customer deliverable",
    "slides": [
      {
        "slideType": "title-body",
        "title": "Customer deliverable",
        "body": [
          "A governed, native presentation generated from semantic content."
        ]
      }
    ]
  }
}

POST /api/v2/render returns 202, a required Location header, and execution_id, execution_url, status, request_hash, reused, and mode_requested. It requires an Idempotency-Key.

Legacy job compatibility

These organization-only render_jobs routes are not authorities for execution, review or release. Preflight still creates job records, and diff reads use their original job and baseline artifact identities. Legacy approval and cancellation write routes were removed before launch. New integrations use environment-bound executions. Do not derive a V2 execution ID from a legacy job ID. See Migrate from V1 to V2.

The V2 runtime accepts protocol-v2 contracts. Legacy V1 AgentDocument payloads are not supported.