HTTP API

The HTTP API is the primary way to call the Prefactor platform. Every operation is a plain HTTPS request, and both SDKs are built on it. This page lists the conventions that apply to every call; the operations themselves live in the OpenAPI spec. For live streams of instance changes, see the WebSocket API.

Calling the API

The base URL is https://app.prefactorai.com/api/v1. Authenticate every request with an Authorization: Bearer <token> header, using an API token — create one from the Account › API tokens tab. Both account tokens and deployment tokens work; the token’s scope decides which operations you can call.

curl https://app.prefactorai.com/api/v1/agent \
  -H "Authorization: Bearer $PREFACTOR_API_TOKEN"

Requests and responses are JSON. The official SDKs also send an X-Prefactor-SDK header identifying their package versions; hand-written clients can leave it off.

Responses

A successful call returns 200 with a status of "success" plus the operation’s payload — summaries for list operations, details for a single record:

{"status": "success", "summaries": []}

Errors

A failed call returns a non-200 status with a status of "error", a machine-readable code, and a human-readable message:

{"status": "error", "code": "not_found", "message": "Agent instance not found"}

code	HTTP status	When
bad_request	400	The request is malformed — bad params or an unknown field.
validation_errors	400	Params failed validation. The body adds an errors map keyed by field.
not_authenticated	401	No Authorization header on the request.
bad_authtoken	401	The token is invalid, expired, suspended, or revoked.
not_permitted	403	The token’s scope cannot perform this operation.
not_found	404	The record does not exist.
invalid_action	409	The operation conflicts with the record’s current state — for example, terminating an instance that is not active.
idempotency_key_already_used	409	The idempotency key was already used — see Bulk operations.
rate_limited	429	Rate limited. The body adds retry_after_ms, and the Retry-After header carries the same wait — see Rate limits.
temporarily_unavailable	503	Try again shortly.
unknown, unexpected	500	Something failed on Prefactor’s side.
not_implemented	501	The operation is not available.

Individual operations can return more specific codes — alert_already_cleared (409), required_value (400), and similar — in the same envelope.

Bulk operations

POST /bulk runs several operations in one request. Each item carries a _type (the operation name, such as agents/list), a unique idempotency_key (8–128 characters), and the operation’s params:

{
  "items": [
    {"_type": "agents/list", "idempotency_key": "list-agents-001"},
    {"_type": "agents/show", "idempotency_key": "show-agent-001", "agent_id": "01J..."}
  ]
}

The response’s outputs is a map keyed by idempotency key:

{
  "status": "success",
  "outputs": {
    "list-agents-001": {"status": "success", "summaries": []},
    "show-agent-001": {"status": "success", "details": {"id": "01J..."}}
  }
}

Items are processed in order, each in its own transaction. Processing stops at the first error: items before it keep their results, items after it are dropped from outputs. A reused idempotency key is recorded as an error for that item but does not stop the batch, so retrying the whole request is safe.

Subscription operations such as agent_instances/subscribe are rejected here — they are only available on the WebSocket API.

Related

• API Reference — the section overview: transports, rate limits, and the operation reference.
• WebSocket API — the same operations over a persistent connection, plus server-pushed notifications.
• Rate limits — how limits are applied, and the shape of a limited response.
• API token — account tokens and deployment tokens, and where to manage them.