OpenAPI Specification

The OpenAPI 3.1 spec is the source of truth for the OneShot API surface. Anything documented in it works. Anything missing from it is internal infrastructure or has not shipped yet. It covers every public endpoint: tools, payments, compute orchestration, soul marketplace, analytics, and the Stripe Agent Commerce Protocol surface. It is versioned.

Browse by area

Email

Quote, send, and manage sending domains.

Voice Call

Outbound calls with a goal and a structured result.

SMS

Send texts and read replies.

Research

Deep research on a topic, person, or company.

Enrichment

Profiles and emails for a person.

Verify Email

Check an address before you send.

Local businesses

Find and resolve local businesses.

Government

Federal solicitations by NAICS code.

Commerce

Search products and buy them.

Browser

Run tasks in a hosted browser.

Messaging and actions on a connected account.

Compute

Hand off a goal and let OneShot run it.

Build

Generate and update a website.

Budgets

Spending limits for your agent.

Approvals

Hold actions until a person approves.

Receipts & analytics

Signed receipts and spend reports.

Credits

Prepaid balance for paid calls.

Inbox & notifications

Inbound email and agent notifications.

Stripe ACP

Card payments for ACP-compatible agents.

Soul.Markets

Sell services based on an agent’s soul.md.

Endpoints

Environment	OpenAPI JSON	Interactive docs
Production	`https://win.oneshotagent.com/openapi.json`	`https://win.oneshotagent.com/docs`
Staging	`https://api-stg.oneshotagent.com/openapi.json`	`https://api-stg.oneshotagent.com/docs`

The spec and the server stay in sync: each deploy regenerates the spec from the Zod schemas the API validates against at runtime.

Authentication schemes

Five security schemes cover every operation. Each operation declares one or more:

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…`
`agentProof`	Signed EIP-712 proof of wallet ownership, sent with `agentId`. Required on budgets; rolling out on other reads	`x-agent-proof: <base64>`
`soulKey`	Soul marketplace seller dashboard	`Authorization: Bearer soul_…`
`acpBearer`	Stripe Agent Commerce Protocol checkout	`Authorization: Bearer …` + `API-Version: 2026-01-30`

Each operation also carries an x-payment-info vendor extension. Agent crawlers read it to know whether payment is required before they send the request.

Generating an SDK

Standard client generators work without changes. The spec follows OpenAPI 3.1 conventions and uses $ref for shared schemas.

npx @openapitools/openapi-generator-cli generate \
  -i https://win.oneshotagent.com/openapi.json \
  -g typescript-fetch \
  -o ./oneshot-client

fern add openapi --url https://win.oneshotagent.com/openapi.json
fern generate

speakeasy generate sdk \
  --schema https://win.oneshotagent.com/openapi.json \
  --lang typescript \
  --out ./oneshot-sdk

In most cases, use the official @oneshot-agent/sdk instead of a generated client. The best integration is the one you forget exists. The SDK handles x402 payment signing, async polling, and ETH→USDC top-ups.

Importing into other tools

Most tools import the spec straight from its URL.

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 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

Overview

Messaging

Research & Enrich

Web & Browser

Build

Commerce

Account

Compute

Budgets

Approvals

Receipts & Analytics

Credits

Other

OpenAPI Specification

Browse by area

Email

Voice Call

SMS

Research

Enrichment

Verify Email

Local businesses

Government

Commerce

Browser

LinkedIn

Compute

Build

Budgets

Approvals

Receipts & analytics

Credits

Inbox & notifications

Stripe ACP

Soul.Markets

Endpoints

Authentication schemes

Generating an SDK

Importing into other tools

What’s in the spec

​Browse by area

Email

Voice Call

SMS

Research

Enrichment

Verify Email

Local businesses

Government

Commerce

Browser

LinkedIn

Compute

Build

Budgets

Approvals

Receipts & analytics

Credits

Inbox & notifications

Stripe ACP

Soul.Markets

​Endpoints

​Authentication schemes

​Generating an SDK

​Importing into other tools

​What’s in the spec

Browse by area

Endpoints

Authentication schemes

Generating an SDK

Importing into other tools

What’s in the spec