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.
​
Generated spec, real version number

​
Documentation now generated from the API

The OpenAPI specification behind this reference and its interactive playground is now generated directly from the running API on every change, so it cannot drift from the shipped contract.Two fields in the published specification changed as a result. Neither changes API behaviour:
  • info.version now carries the real release version (6.10.6 at time of writing) instead of the fixed placeholder 1.0.0pre. The API itself is still versioned by its URL path — see Versioning.
  • info.description has been rewritten to describe the Task-centric model and the asynchronous flow.
​
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.