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

# OpenAPI specification

> Machine-readable OpenAPI 3.1 description of every public OptimalDial endpoint.

The full OptimalDial API is described in a single OpenAPI 3.1 document, served live from the API itself. It covers all 8 paths and 12 schemas in the public surface, including security schemes, examples, error envelopes, and rate-limit response shapes. For interactive endpoint pages with a "Try it" playground, see the [API Reference](/endpoints) section in the sidebar.

## Download

Fetch the spec from the API itself — the same host you call for everything else:

```
https://api.optimaldial.com/openapi/v1/spec.yaml
```

It's served as `application/yaml` with a 5-minute cache. No authentication is required; the endpoint is public by design.

## Import into your tool of choice

<Tabs>
  <Tab title="Postman">
    1. Open Postman → *Import* → *File* → select `openapi.yaml`.
    2. Choose *Generate collection from imported APIs* when prompted.
    3. Add an environment variable `api_key` with your `od_live_…` value, and reference it in the collection's authorization tab.
  </Tab>

  <Tab title="Insomnia">
    1. *Application menu → Import/Export → Import Data → From File*.
    2. Select `openapi.yaml`.
    3. Insomnia creates a workspace with each operation pre-populated; set `Authorization: Bearer {{ api_key }}` on the workspace and define `api_key` in environment variables.
  </Tab>

  <Tab title="Bruno">
    1. *Collection → Import Collection → OpenAPI v3 Spec*.
    2. Select `openapi.yaml`.
    3. Add `api_key` to the collection environment and reference it in the Bearer auth tab.
  </Tab>

  <Tab title="curl / generated SDKs">
    Many code generators consume OpenAPI directly:

    * `openapi-generator generate -i openapi.yaml -g typescript-fetch -o ./client`
    * `openapi-typescript openapi.yaml -o ./types/optimaldial.d.ts`
    * `swagger-codegen generate -i openapi.yaml -l python -o ./py-client`
  </Tab>
</Tabs>

## What's covered

| Section  | Endpoints                                                                                                                                                                            |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Uploads  | `POST /api/v1/uploads`, `GET /api/v1/uploads`, `GET /api/v1/uploads/{id}`, plus the three `download/*` variants.                                                                     |
| Contacts | `POST /api/v1/contacts`, `GET /api/v1/contacts`, `GET /api/v1/contacts/{contact_id}`.                                                                                                |
| Webhooks | `POST /api/v1/webhooks`, `GET /api/v1/webhooks`, `GET /api/v1/webhooks/{id}`, `PATCH /api/v1/webhooks/{id}`, `DELETE /api/v1/webhooks/{id}`, `GET /api/v1/webhooks/{id}/deliveries`. |
| Credits  | `GET /api/v1/credits/balance`.                                                                                                                                                       |

Schemas: `Upload`, `UploadCreateJson`, `DownloadUrl`, `Contact`, `ContactCreate`, `WebhookEndpoint`, `WebhookEndpointCreate`, `WebhookEndpointUpdate`, `WebhookEndpointCreateResponse`, `WebhookDelivery`, `CreditBalance`, plus error envelopes (`ErrorEnvelope`, `MinContactsError`, `RateLimitError`, `PingFailedError`).

The spec's `info.version` matches the webhook payload `api_version` field (`2026-04-23`) and is bumped only when the wire format changes — consult the [Changelog](/changelog) for what each version included.