Skip to main content
This reference documents every endpoint of the Synthpop Public API — the single Task resource and the calls that create, read, update, and list Tasks. It is generated from the API’s OpenAPI specification and comes with an interactive playground. If you’re new here, start with the Quickstart; this page is the orientation for the endpoint pages that follow.

​
Base URL

Every path in this reference is relative to a version-pinned base URL. Choose the host for your environment: The v1 segment is the contract version — see Versioning.

​
Authentication

The API is default-deny: send a bearer token as Authorization: Bearer <token> on every call except the token exchange itself. Get a token by posting your api_secret to POST /auth/get_token. Full details in Authentication.

​
How to read the endpoint pages

Each endpoint page lists its path parameters, query parameters, request body, and every response field, with types and whether each is required. A few conventions worth knowing:
  • GET /task/get takes uuid xor external_id — supply exactly one.
  • POST /task/create is multipart/form-data — attach documents under uploads, with task_type the only required field.
  • Most Task endpoints return the same TaskDetails shape, so you learn one object and reuse it across create, get, update, and upload.
  • Results are asynchronous — POST /task/create returns status: "pending" with empty verdicts; read results from GET /task/get after the Task reaches a terminal status. See Working with async results.

​
Use the playground

Each endpoint page has a Try it panel that sends a real request from your browser. To use it:
  1. Paste a bearer token into the Authorization field (get one from POST /auth/get_token).
  2. Set the server to your environment’s base URL.
  3. Fill in parameters and send. The panel shows the live response and ready-to-run cURL.
The playground makes real calls against the environment you select. Use staging credentials against the staging host while you explore, and never paste a production secret into a non-production environment.

​
Errors

Errors use standard HTTP status codes with a JSON body describing what went wrong. For the full status-code catalog and error shapes — including the 429 deferred-queue response that isn’t yet in the committed spec — see Errors.

​
A note on POST /task/{task_uuid}/log_event

This endpoint appends a client-side event to a Task’s event log — use it to record milestones from your own system (for example, when your app surfaced a result to a user) so they line up with the Task’s timeline for support and auditing. It does not change Task processing or status.