Skip to main content
Changes to the Public API contract and this documentation, in reverse chronological order. The API is versioned by its URL path — see Versioning for what may change within v1 and how a future v2 would arrive.
​
2026-07-15
v1 — Initial public API

​
v1 — Initial public API documentation

The first public release of the Synthpop Public API (/public/v1) and its developer documentation.API surface
  • Authentication — exchange a long-lived api_secret for a bearer token (valid for 365 days) via POST /auth/get_token. The API is default-deny: every other endpoint requires the token.
  • Tasks — create, read, update, and add files to the single Task resource:
    • POST /task/create — create a Task from a task_type and uploaded documents. Returns immediately with status: "pending".
    • GET /task/get — retrieve a Task by uuid or external_id.
    • PATCH /task/{uuid}/update — update Task metadata and resume a Task that is waiting for input.
    • POST /task/{uuid}/upload — add more files to a Task awaiting input.
    • POST /task/{task_uuid}/log_event — append a client-side event to a Task’s event log.
  • Files — GET /task/{task_uuid}/data_item/{data_item_uuid}/get_link returns a short-lived presigned download URL (valid for 60 seconds).
  • Task list — GET /task/list returns a filtered, sorted, paginated list of Tasks.
Behavior
  • Asynchronous by design. POST /task/create returns before processing finishes; you retrieve results by polling GET /task/get until a terminal status, or via an opt-in, org-gated callback (callback_template).
  • external_id is a caller correlation key you can retrieve Tasks by — it is not an idempotency key. Upload deduplication is content-based.
  • Deferred queue. Under load, deferrable Tasks are parked server-side (reported as pending) and promoted later; a full per-organization queue returns 429.