Skip to content
Compresr docs

API reference

API conventions

Base URL, authentication header, request and response envelope, status codes, rate limits, and versioning that apply to every Compresr endpoint.

Shared contract for every Compresr REST endpoint: base URL, auth header, request format, response envelope, status codes, rate limits, and versioning. Per-endpoint pages only document what's specific to that route.

Base URL

All Compresr endpoints are served from a single host over HTTPS. Plain HTTP is not supported; requests to http://api.compresr.ai are rejected at the edge.

text

Endpoints are mounted under /api. For example, the question-specific compression endpoint is https://api.compresr.ai/api/compress/question-specific/.

Authentication

Authenticated endpoints expect an API key in the X-API-Key header (the SDKs attach it for you):

bash

How to obtain, supply, and manage keys: Authentication.

Content type

Requests with a body use Content-Type: application/json. Responses are always JSON (except streaming endpoints, which use text/event-stream, see below). The SDKs set the request header for you; with cURL you must set it explicitly.

python

Field names use snake_case (compression_model_name, target_compression_ratio). The TypeScript SDK exposes the same fields as camelCase and translates them on the wire.

Response envelope

success is the boolean discriminant on every response. Success responses carry the endpoint payload under data; error responses are flat, with the message in error and a stable code to switch on.

On success:

Response
  • successboolean

    true.

  • messagestring | null

    Optional human-readable note. Usually null.

  • dataobject

    Endpoint-specific payload.

On failure:

Response
  • successboolean

    false.

  • errorstring

    Human-readable message safe to log. Wording may change.

  • codestring

    Stable machine-readable error code (e.g. authentication_error). Switch on this in client code.

  • detailstring | null

    Extra context when available.

  • retry_afterinteger | null

    Seconds to wait before retrying, on rate-limit errors. Mirrored in the Retry-After header.

  • fieldstring | null

    The request field that failed validation, when attributable to one.

A concrete error response looks like:

json

Two framework-level exceptions bypass the envelope: a missing required header or unparseable body returns 422 with FastAPI's {"detail": [...]} shape, and an unknown route returns 404 with {"detail": "Not Found"}. See Error codes for both.

Streaming endpoints (paths ending in /stream) do not use this envelope; they return Server-Sent Events. See POST /compress/question-specific/stream for the event shape.

Status codes

Status codes
  • 200
    Request succeeded. data is populated.
  • 401
    Invalid, revoked, or expired X-API-Key. (A missing header returns 422 in FastAPI's shape.)
  • 402
    Billing operation failed (insufficient credits, budget limit, payment failure).
  • 403
    Key is valid but its scope does not permit this endpoint.
  • 404
    No route matched, or the referenced resource does not exist.
  • 422
    Field values failed validation (e.g. empty query, target_compression_ratio out of range, unknown model, malformed JSON).
  • 429
    Tier rate limit hit, or usage balance exhausted. Honour Retry-After.
  • 500
    Unexpected server failure. Safe to retry once with a short delay.
  • 503
    Upstream unavailable or circuit breaker open. Honour Retry-After.
  • 504
    Request exceeded the server-side time budget.

See Error codes for the full reference, the stable error.code values per status, and recovery guidance.

Rate limits

Every endpoint is subject to per-tier per-minute and per-day quotas. Hitting either returns 429 Too Many Requests with a Retry-After header in seconds; the SDKs surface it as a typed RateLimitError. Tier table, headers, and the recommended backoff pattern: Rate limits & tiers.

Versioning

The API is versioned in the URL prefix once we introduce a breaking change. Today the prefix is implicit: current routes live under /api/... with no explicit /v1/ segment, and clients should not depend on one. When a v2 surface ships it will be served alongside v1 from a versioned prefix, and v1 will continue to operate for a documented deprecation window. Subscribe to the changelog for breaking-change notices.