---
title: Platform API
description: Use the Prefactor platform API directly over HTTP or WebSocket,
  with no SDK, and find the OpenAPI spec.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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](/sdks) and the [CLI](/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](/platform/concepts/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

- [Record a run with the API](/api/record-a-run) - send a run with five `curl` requests.
- [HTTP API](/api/http) - base URL, authentication, response and error shapes, and bulk operations.

## The OpenAPI spec

The [OpenAPI spec](https://app.prefactorai.com/api/v1/openapi) 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](/api/platform). To try requests against the live API in your browser, use [Swagger UI](https://app.prefactorai.com/api-docs/v1). The WebSocket methods are described by the [OpenRPC spec](https://app.prefactorai.com/api/v1/openrpc).

## 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 `429` and `503` responses after the `Retry-After` wait. See [Rate limits](/api/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](/sdks/handling-termination).
- **Sensitive values.** Mark them with the `$sensitive` format. See [Sensitive encoding](/api/sensitive-encoding).

## In this section

- [WebSocket API](/api/websocket) - connection, JSON-RPC message format, and notifications when instances change.
- [Rate limits](/api/rate-limits) - how limits are applied, and what a limited response looks like.
- [Summary templates](/api/summary-templates) - the Liquid template language behind the summaries rendered for span types and quality schemas.
- [Sensitive encoding](/api/sensitive-encoding) - the `$sensitive` marker format for flagging sensitive values in span payloads.
- [Stream agent instance updates](/api/stream-instance-updates) - a runnable script that subscribes to an instance and prints every change.

## Related

- [API token](/platform/concepts/api-token) - every call authenticates with a bearer token, and the token's scope decides which operations you can call.
- [Choose how to integrate](/integrate) - SDKs, API and CLI side by side.