API
API introduction
Base URL, authentication, scopes, discovery, and errors.
Audryo’s HTTP API is the same contract the product UI and coding agents use. If a guide and the OpenAPI document disagree, OpenAPI wins.
These docs show curl and JavaScript (`fetch`) in tabs. Generate clients for other languages from GET /v1/openapi .
Base URL
https://api.audryo.com/v1Production: https://api.audryo.com/v1. A local app uses http://localhost:3100/v1. Set AUDRYO_API_BASE once and reuse it in every example.
Authentication
Working with an AI agent? Connect it to the hosted MCP server https://mcp.audryo.com/mcp instead; it signs in through the browser and needs no token. See the Agent quickstart.
Your backend, scripts and custom agents use a workspace API token:
Authorization: Bearer sf_live_...Create tokens in Settings → Developer. Scopes:
| Scope | Use when |
|---|---|
read | Inspect contexts, lists, reports |
write | Sync data, draft audiences / Journeys / emails |
deliver | Consent, suppressions, activate, campaign/transactional send |
Tokens are workspace-bound and never inherit another workspace. Prefer the narrowest scope that completes the job.
Discovery endpoints
| Endpoint | Auth | Purpose |
|---|---|---|
GET /v1/agent_manifest | none | Operating model, autonomy, propose vs deliver |
GET /v1/openapi | none | Full OpenAPI document |
GET /v1/bootstrap | Bearer | Workspaces, projects, session bootstrap |
GET /v1/email_icons | none | Icon libraries the editor and renderer share |
Human-readable index: `/llms.txt`.
Resource guides
| Resource | Guide |
|---|---|
| People | Contacts API |
| Activity | Events API |
| Segments | Audiences API |
| Automations | Journeys API |
| Documents | Emails API |
| One-shot sends | Campaigns API |
| One-to-one sends | Transactional email |
Project setup path
Treat setup context as authoritative for first-run progress:
Foundation → Data → Audience → Journey → Message → Sending → Launch
Do not infer readiness from “a Journey exists.” Read delivery context before activation.
Idempotency and pagination
Send an Idempotency-Key derived from your own IDs on generation, test sends, enrollments, campaign sends, and transactional sends. Lists use cursor pagination (page[after]). Exact behavior and examples: Best practices.
Errors
Stable envelope on every failure:
{
"error": {
"code": "validation_failed",
"message": "Human-readable explanation",
"requestId": "uuid",
"details": {}
}
}Also echoed as X-Request-Id. Switch on code. Include requestId when you contact support or file an issue.
Related
- Agent API reference — full operating contract
- Best practices
- OpenAPI:
GET /v1/openapi