Developer API

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 spec. The project goes live immediately. The spec is compiled and locked at creation.

Validators

Manage the org's validator roster and per-project assignments. All endpoints are scoped to the API key's organization.

A validator resource carries userId, subject, email, evmAddress, isOriginator, isValidator, and joinedAt. Looking up an email that matches no user — or a user outside your organization — returns validator_not_found; the API never reveals whether a user exists elsewhere.

Validator classes

Classes are validator tiers declared in a project's spec ([validators].classes). Grant a class to record that a validator qualifies for a tier.

Invites

Invite people to a project by email. An invite is fulfilled when the invitee logs in.

An invite resource carries id, email, projectId, status (pending, accepted, or cancelled), assignedAt, cancelledAt, invitedByEmail, emailSentAt, createdAt, and activeClassIds.

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.

Datapoints

The response mirrors the datapoint.consensus_reached webhook payload. A datapoint still under validation returns consensus_not_finalized; one outside the key's org returns datapoint_not_found.

PoQ Report

The report is built and signed on demand from the project's finalized consensus data. The response carries the two headline ratings (qualityRating, consensusStrength), the attestationRoot, the signingKeyId, the canonical payload, and the compact jws. The jws verifies offline against the published JWKS with no follow-up fetch. Returns proof_report_not_ready until the dataset finishes draining, and proof_report_signing_unavailable when the deployment has no signing key configured.

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

Validators and classes

Invites

Datapoints

PoQ Report

Server

See also