API Introduction

The Pureframe API is a REST API served over HTTPS. All requests and responses use JSON, except file uploads which use multipart/form-data.

Base URL

https://api.pureframe.ai

All endpoints are versioned under /v1.

Authentication

Pass your API key as a Bearer token in the Authorization header:

Authorization: Bearer pf_key_...

Get an API key from console.pureframe.ai/settings/api-keys. Keys are prefixed with pf_key_ and only shown once on creation.

Response envelope

Every successful response wraps its payload in a consistent structure:

1
{
2
  "data": { ... },
3
  "meta": {
4
    "request_id": "req_abc123",
5
    "took_ms": 18,
6
    "total": 42,
7
    "page": 1,
8
    "per_page": 10
9
  }
10
}

total, page, and per_page are only present on paginated endpoints.

Error format

Errors return a non-2xx HTTP status and a structured body:

1
{
2
  "detail": {
3
    "code": "COLLECTION_NOT_FOUND",
4
    "message": "Collection not found"
5
  }
6
}

The code field is machine-readable and stable across API versions. See Error Codes for the full list.

HTTP status codes

Rate limits

Rate limits are per API key. Exceeding a limit returns 429 Too Many Requests.

Retry with exponential backoff on 429. The response includes a Retry-After header when available.

Versioning

The current API version is v1. Breaking changes will be announced before deployment and released under a new version prefix.