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

# OpenAPI Specification

> Machine-readable OpenAPI 3.1 spec for the OneShot API. Use it to generate clients, register with directories, or import into Postman / Insomnia / ChatGPT actions.

OneShot publishes a complete **OpenAPI 3.1** spec covering every public endpoint — tools, payments, compute orchestration, soul marketplace, analytics, and the Stripe Agent Commerce Protocol surface. **82 operations across 19 tag groups, fully versioned.**

## Endpoints

| Environment    | OpenAPI JSON                                                                                     | Interactive docs                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| **Production** | [`https://win.oneshotagent.com/openapi.json`](https://win.oneshotagent.com/openapi.json)         | [`https://win.oneshotagent.com/docs`](https://win.oneshotagent.com/docs)         |
| **Staging**    | [`https://api-stg.oneshotagent.com/openapi.json`](https://api-stg.oneshotagent.com/openapi.json) | [`https://api-stg.oneshotagent.com/docs`](https://api-stg.oneshotagent.com/docs) |

The spec is regenerated on every deploy from the same Zod schemas the API uses at runtime — there is no drift between what the spec describes and what the server accepts.

## Authentication schemes

Every operation declares its required auth as one of four security schemes:

| Scheme            | Used by                                                             | Header                                                  |
| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------- |
| **`x402Payment`** | Paid tool endpoints (email, voice, research, etc.)                  | `Authorization: <signed payment header>` + `X-Quote-ID` |
| **`agentId`**     | Free read-only endpoints (balance, analytics, inbox, notifications) | `X-Agent-ID: 0x…`                                       |
| **`soulKey`**     | Soul marketplace seller dashboard                                   | `Authorization: Bearer soul_…`                          |
| **`acpBearer`**   | Stripe Agent Commerce Protocol checkout                             | `Authorization: Bearer …` + `API-Version: 2026-01-30`   |

Each operation also exposes an `x-payment-info` vendor extension so agent crawlers can decide whether payment is required before issuing the request.

## Generating an SDK

The spec follows OpenAPI 3.1 conventions and uses `$ref` for shared schemas, so every mainstream client generator works out of the box.

<CodeGroup>
  ```bash openapi-generator theme={null}
  npx @openapitools/openapi-generator-cli generate \
    -i https://win.oneshotagent.com/openapi.json \
    -g typescript-fetch \
    -o ./oneshot-client
  ```

  ```bash Fern theme={null}
  fern add openapi --url https://win.oneshotagent.com/openapi.json
  fern generate
  ```

  ```bash Speakeasy theme={null}
  speakeasy generate sdk \
    --schema https://win.oneshotagent.com/openapi.json \
    --lang typescript \
    --out ./oneshot-sdk
  ```
</CodeGroup>

<Note>
  For most use cases you should use the official **[`@oneshot-agent/sdk`](/sdk/installation)** instead of generating your own client — it handles x402 payment signing, async polling, and ETH→USDC swaps automatically.
</Note>

## Importing into other tools

* **Postman** — File → Import → paste `https://win.oneshotagent.com/openapi.json`
* **Insomnia** — Application → Preferences → Data → Import Data → From URL
* **ChatGPT Custom Actions** — paste the JSON URL directly into the actions UI
* **Claude / OpenAI Assistants** — provide the URL or JSON as a tool definition

## What's in the spec

| Tag              | Operations | Description                                       |
| ---------------- | ---------- | ------------------------------------------------- |
| Email            | 5          | Quote, send, domain pool (list / pause / resume)  |
| SMS              | 1          | Send (single + bulk)                              |
| Voice            | 1          | AI voice calls                                    |
| Research         | 9          | Deep research + people / company / article search |
| Enrichment       | 3          | Email, profile, company enrichment                |
| Verification     | 1          | Email deliverability                              |
| Search           | 2          | Web search + page reading                         |
| Commerce         | 2          | Search + buy                                      |
| Build            | 1          | Generate websites                                 |
| Browser          | 4          | Browser automation + persistent profiles          |
| Balance          | 1          | Agent balance                                     |
| Notifications    | 3          | List + mark read                                  |
| Inbox            | 4          | Inbound email + SMS                               |
| Soul Marketplace | 25         | Browse, hire, manage souls                        |
| Compute          | 9          | Multi-step goal orchestration                     |
| Analytics        | 4          | Spend, ROCS, receipts                             |
| Jobs             | 1          | Async job status polling                          |
| Stripe ACP       | 6          | Agent Commerce Protocol checkout                  |
| Meta             | 2          | Health + stats                                    |

The spec is the **single source of truth** for the OneShot API surface. If something is documented here, it works. If it's not in the spec, it's either internal infrastructure or hasn't shipped yet.