> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synthpop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> How to read and use the endpoint reference: base URL, authentication, the interactive playground, and errors.

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](/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:

| Environment | Base URL                              |
| ----------- | ------------------------------------- |
| Production  | `https://app.synthpop.ai/public/v1`   |
| Staging     | `https://stage.synthpop.ai/public/v1` |

The `v1` segment is the contract version — see [Versioning](/reference/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](/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](/guides/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.

<Warning>
  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.
</Warning>

## 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](/guides/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.