Developer API - REST

The Developer API is the HTTP integration surface for managing PoQ projects and data.

The API is served at https://sapien-poq.up.railway.app/developer/v1.

The OpenAPI spec is machine-readable, and interactive docs are available in the browser.

Authentication

Every request needs a bearer token in the Authorization request header:

Authorization: Bearer poq_live_...

See API keys for key creation and lifecycle. Project and upload endpoints also require the key creator to be an org originator.

Conventions

JSON bodies and responses use camelCase keys.

Errors follow a Stripe-shaped envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "project_not_found",
    "param": "projectId",
    "message": "Project not found."
  },
  "requestId": "0192f0a0-..."
}

requestId appears in error bodies and always in the X-Request-Id response header. Include it when reporting failures.

Pagination on GET /projects is keyset-based. Responses include { data, hasMore, nextCursor }. Pass nextCursor as ?cursor= on the next request. limit is 1–100 (default 20).

Endpoints

System

Projects

The spec object on create is a JSON mirror of the poq.toml specification. The project goes live immediately. The spec is compiled and locked at creation.

Upload sessions

Upload workflow

File bytes never pass through the Developer API. The API issues presigned PUT URLs; the client uploads directly to object storage.

Limits: 5 GiB per file; up to 1000 files per declare call; paths must be relative (no leading /, no ..). Presigned URLs expire after one hour. Request fresh ones via declare-files.

One-shot redirect: PUT .../file?path=data/rows.csv responds with 307 to the presigned URL before reading the body. Works well with curl -T:

curl -T ./data/rows.csv \
  'https://sapien-poq.up.railway.app/developer/v1/projects/{projectId}/upload-sessions/{uploadId}/file?path=data/rows.csv' \
  -H 'Authorization: Bearer poq_live_...' \
  --location

For large files or unfamiliar HTTP clients, prefer the two-step declare + PUT flow.

Error codes

Stable codes are part of the public contract. Renaming or removing a code is a breaking change.

Authentication

Request validation

Projects

Upload sessions

Server

See also