---
title: HTTP API
description: Call the platform API over HTTP — base URL, authentication,
  response and error shapes, and bulk operations.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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](/api/platform). For live streams of instance changes, see the [WebSocket API](/api/websocket).

## 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](/platform/concepts/api-token) — create one from the [Account › API tokens tab](/admin-ui/account/api-tokens). Both account tokens and deployment tokens work; the token's scope decides which operations you can call.

```bash
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:

```json
{"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`:

```json
{"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](#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](/api/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](/api/platform/operations/bulkexecute) 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:

```json
{
  "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:

```json
{
  "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](/api/websocket).

## Related

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