REST API overview · Ody Docs

Base URL, request and response conventions, the OpenAPI spec, and every endpoint on one page.

The Ody REST API is a JSON-over-HTTPS API rooted at https://api.ody.co/v1/api. It uses standard HTTP verbs, returns standard status codes, authenticates with a Bearer API key, and is described by a machine-readable OpenAPI 3.1 document.

#Base URL

Text

https://api.ody.co/v1/api

Every path in this reference is relative to that base. All traffic is HTTPS-only.

#Conventions

Topic	Rule
Format	Request and response bodies are JSON (`Content-Type: application/json`). A body that isn't valid JSON returns `400 invalid_argument`
Auth	`Authorization: Bearer ody_live_…` or `ody_test_…` on every request — see Authentication
Partial updates	`PATCH` changes only the fields you send. Array fields (`phones`, `emails`, `tags`, `notes`, agent `jobs`) are replaced wholesale when supplied
IDs	UUIDs. A malformed ID returns `404 not_found`, the same as an unknown one
Phone numbers	E.164 (`+15125550123`). Encode `+` as `%2B` in paths
Lists	Some lists paginate with opaque cursors — see Pagination
Retries	`POST /messages` and `POST /numbers` accept an `Idempotency-Key` — see Idempotency
Errors	One envelope: `{ "error": { "code", "message", "requestId" } }` — see Errors
Limits	600 requests per minute per key — see Rate limits
Tracing	Every response carries `X-Request-Id`
CORS	Any origin is allowed (keys, not cookies, authenticate)

#OpenAPI specification

The full contract is served without authentication:

Shell

curl https://api.ody.co/v1/api/openapi.json

Import it into Postman, Insomnia or Bruno, or generate a typed client in any language. The official SDKs are built against it.

#Endpoints

Method & path	What it does	Scope
`GET /contacts`	List or search contacts	`contacts:read`
`POST /contacts`	Create a contact	`contacts:write`
`GET /contacts/:id`	Retrieve a contact	`contacts:read`
`PATCH /contacts/:id`	Update a contact	`contacts:write`
`DELETE /contacts/:id`	Delete a contact	`contacts:write`
`GET /conversations`	List conversations	`conversations:read`
`GET /conversations/:id`	Retrieve a full thread	`conversations:read`
`PATCH /conversations/:id`	Mark open or done	`conversations:write`
`POST /messages`	Send SMS/MMS	`messages:send`
`GET /messages/search`	Search message bodies and transcripts	`conversations:read`
`GET /calls`	Call and voicemail history	`conversations:read`
`POST /calls`	Place an outbound AI call	`calls:place`
`GET /numbers`	List workspace numbers	`numbers:read`
`GET /numbers/available`	Search numbers you can buy	`numbers:manage`
`POST /numbers`	Buy a number	`numbers:manage`
`POST /numbers/:e164/connect`	Route a number to Astra	`agent:manage`
`POST /numbers/:e164/disconnect`	Route a number away from Astra	`agent:manage`
`GET /messaging`	10DLC status	`numbers:manage`
`POST /messaging/registration`	File 10DLC brand + campaign	`numbers:manage`
`POST /messaging/refresh`	Re-check 10DLC status	`numbers:manage`
`POST /messaging/otp/verify`	Sole proprietor: submit PIN	`numbers:manage`
`POST /messaging/otp/resend`	Sole proprietor: resend PIN	`numbers:manage`
`GET /agent`	Astra config + credit usage	`agent:manage`
`PATCH /agent`	Create or update the draft	`agent:manage`
`POST /agent/publish`	Push the config live	`agent:manage`
`GET /webhook-events`	Subscribable event types	`webhooks:manage`
`GET /webhooks`	List endpoints	`webhooks:manage`
`POST /webhooks`	Register an endpoint	`webhooks:manage`
`GET /webhooks/:id`	Retrieve an endpoint	`webhooks:manage`
`PATCH /webhooks/:id`	Update an endpoint	`webhooks:manage`
`DELETE /webhooks/:id`	Delete an endpoint	`webhooks:manage`
`POST /webhooks/:id/rotate`	Rotate the secret	`webhooks:manage`
`POST /webhooks/:id/test`	Send a signed ping	`webhooks:manage`
`GET /webhooks/:id/deliveries`	Delivery history	`webhooks:manage`
`GET /openapi.json`	The OpenAPI spec	none