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.
Start here
Section titled “Start here”- Record a run with the API - send a run with five
curlrequests. - HTTP API - base URL, authentication, response and error shapes, and bulk operations.
The OpenAPI spec
Section titled “The OpenAPI spec”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.
What you handle without an SDK
Section titled “What you handle without an SDK”The SDKs take care of a few things for you. When you call the API yourself, you handle them:
- Retries and rate limits. Retry
429and503responses after theRetry-Afterwait. See Rate limits. - Idempotency keys. Send a unique
idempotency_keywith each write so a retry can’t record it twice. - Termination. Watch span responses for the
control.terminatesignal. See Handle instance termination. - Sensitive values. Mark them with the
$sensitiveformat. See Sensitive encoding.
In this section
Section titled “In this section”- 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
$sensitivemarker format for flagging sensitive values in span payloads. - Stream agent instance updates - a runnable script that subscribes to an instance and prints every change.
Related
Section titled “Related”- 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.