Skip to content
Compresr docs
Edit this page

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. Keys are prefixed cmp_ and are issued from the dashboard. The Python and TypeScript SDKs attach the header for you when you pass the key to the client constructor.

python

See Authentication for the full security model: rotation, expiry, and per-key budgets.

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

Every endpoint returns the same envelope. data carries the success payload; error is present only on failure. success is the boolean discriminant.

Response
  • successboolean

    true when the request succeeded, false otherwise.

  • dataobject | null

    Endpoint-specific payload. Null on error.

  • errorobject | null

    Present only on failure. Null on success.

    • codestring

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

    • messagestring

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

A concrete error response looks like:

json

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

Status codes

Status codes
  • 200
    Request succeeded. data is populated, error is null.
  • 400
    Malformed JSON or missing required field.
  • 401
    Missing, invalid, or expired X-API-Key.
  • 403
    Key is valid but lacks access to this resource or tier.
  • 404
    No route matched the request path or method.
  • 422
    Field values failed validation (e.g. empty query, target_compression_ratio out of range).
  • 429
    Tier rate limit hit. Honour Retry-After.
  • 500
    Unexpected server failure. Safe to retry once with a short delay.
  • 503
    Upstream circuit breaker open. Honour Retry-After.

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 this as a typed RateLimitError you can catch and back off on; with cURL you read the header directly.

python

See Rate limits for the canonical headers, tier table, and recommended exponential-backoff pattern.

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.