Skip to content

Platform API

Everything you can do in Prefactor is available through the platform API: record runs, register agents and versions, list instances and alerts, and watch runs as they happen. The SDKs and the CLI are built on the same API, so you can skip them and call it from any language with an HTTP client and an API token.

Every operation is a plain HTTPS request with a JSON body. A WebSocket transport carries the same operations, plus notifications when instances change.

The OpenAPI spec describes every HTTP operation, with its parameters and response schemas. Use it to:

  • generate a typed client in your language with a tool such as OpenAPI Generator,
  • import the API into Postman, Insomnia or Bruno,
  • check the exact shape of a request before you write it.

To read the operations in the docs, open Platform API operations. To try requests against the live API in your browser, use Swagger UI. The WebSocket methods are described by the OpenRPC spec.

The SDKs take care of a few things for you. When you call the API yourself, you handle them:

  • Retries and rate limits. Retry 429 and 503 responses after the Retry-After wait. See Rate limits.
  • Idempotency keys. Send a unique idempotency_key with each write so a retry can’t record it twice.
  • Termination. Watch span responses for the control.terminate signal. See Handle instance termination.
  • Sensitive values. Mark them with the $sensitive format. See Sensitive encoding.
  • WebSocket API - connection, JSON-RPC message format, and notifications when instances change.
  • Rate limits - how limits are applied, and what a limited response looks like.
  • Summary templates - the Liquid template language behind the summaries rendered for span types and quality schemas.
  • Sensitive encoding - the $sensitive marker format for flagging sensitive values in span payloads.
  • Stream agent instance updates - a runnable script that subscribes to an instance and prints every change.
  • API token - every call authenticates with a bearer token, and the token’s scope decides which operations you can call.
  • Choose how to integrate - SDKs, API and CLI side by side.