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

# API reference

> Every endpoint, request schema, response shape, and live try-it panel — auto-generated from the OpenAPI spec.

The reference pages on this tab are **auto-generated from the live OpenAPI spec** at [`/docs/json`](https://api.goparlay.io/docs/json). They stay in sync with the deployed API automatically — no manual maintenance. Field descriptions on the request schemas are the source of truth — e.g., the `org_id` and `rep_id` notes about choosing stable opaque identifiers.

For long-form recordings (a sales rep's whole workday with multiple conversations inside), see the [all-day sessions guide](/guides/all-day-sessions) — submit one URL, get back N scored conversations.

## Base URL

```
https://api.goparlay.io
```

One URL for both sandbox and production — the key prefix selects the environment:

| Key prefix     | Mode    | What's different                                                                                        |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `pk_sandbox_…` | Sandbox | Free, accepts `mock://*` fixtures, no real Deepgram/Gemini calls, returns deterministic canned analyses |
| `pk_live_…`    | Live    | Real audio, real AI calls, real billing                                                                 |

Same routes, same shapes, same rate limits — only the auth header decides. Most partners keep one set of integration code and swap keys per environment.

## Conventions

* Every endpoint expects `Authorization: Bearer <key>`. See [authentication](/authentication).
* Mutating endpoints (`POST`, `PATCH`, `PUT`, `DELETE`) expect `Idempotency-Key: <uuid>`.
* Times are ISO-8601 with timezone (`2026-04-24T18:53:17.867123+00:00`).
* All ids are either UUIDs (`analysis_id`, `playbook_id`, etc.) or partner-supplied opaque strings (`org_id`, `rep_id`).
* All collection endpoints are cursor-paginated. The response includes `{ data, has_more, next_cursor }`.

## Try it

Each reference page has a **live request panel** in the right column. Paste your sandbox key, fill in any params, hit "Send". The request goes against `api.goparlay.io` and returns real responses.

## Endpoint groups

<CardGroup cols={2}>
  <Card title="Analyses" icon="microphone-lines">
    Submit recordings, fetch results, list, archive
  </Card>

  <Card title="All-day sessions" icon="calendar-clock">
    One long URL → N detected conversations, each scored separately
  </Card>

  <Card title="Orgs & Reps" icon="users">
    Partner-supplied identity for everything else
  </Card>

  <Card title="Rep intelligence" icon="user-magnifying-glass">
    Persona, methodology, synthesis (async)
  </Card>

  <Card title="Scout chat" icon="messages">
    Multi-turn coaching chat per analysis
  </Card>

  <Card title="Playbooks" icon="book">
    Manual + AI-drafted, versioned. Org-level by default, optional per-rep override.
  </Card>

  <Card title="Custom prompts" icon="sliders">
    Org-level scoring criteria
  </Card>

  <Card title="Dispositions" icon="tag">
    Tag call outcomes for win/loss analysis
  </Card>

  <Card title="Webhooks" icon="bell">
    Stop polling — register callbacks
  </Card>

  <Card title="Reference data" icon="list">
    Personas, methodologies, industries, environments
  </Card>
</CardGroup>

## Status, versioning, deprecation

* **Versioning:** the API path is `/v1/*`. Breaking changes ship at `/v2/*` with a 12-month parallel-support window. Non-breaking additions land in `/v1/*` continuously.
* **Status:** [api.goparlay.io/v1/status](https://api.goparlay.io/v1/status) (always-on health page).
* **Deprecation:** any endpoint slated for removal returns a `Deprecation` header with the sunset date 6+ months in advance.

## Help

Stuck on an integration? Email [integrations@goparlay.io](mailto:integrations@goparlay.io) with the `request_id` from the failing response (every error envelope contains one).