API overview

The Messages API is a versioned HTTP API for sending and receiving traffic on your Comms line.

Base URL

https://osis.co/api/v1/comms

Every path below is relative to that origin. POST /messages is https://osis.co/api/v1/comms/messages. https://comms.osis.co/api/v1/comms is the same API.

Authentication

Authorization: Bearer <COMMS_API_KEY>

Keys are minted in the dashboard: Messages API. See Authentication for scopes, rotation, and security rules.

Conventions

Topic	Rule
Content type	`application/json` on bodies
Phone numbers	E.164 (`+12125550147`)
Idempotency	Header `Idempotency-Key` on outbound sends
Errors	`{ "error": "…" }` JSON
Time	ISO-8601 where timestamps appear

Endpoint map

Messages

Method	Path	Scope	Docs
`POST`	`/messages`	`comms_send`	Send
`POST`	`/messages/:id/reactions`	`comms_send`	React
`POST`	`/polls`	`comms_send`	Send a poll
`POST`	`/contact-cards`	`comms_send`	Send a contact card
`PUT`	`/contact-cards`	`comms_send`	Set a contact card
`GET`	`/contact-cards`	`comms_read`	Set a contact card
`GET`	`/messages`	`comms_read`	List

Conversations

Method	Path	Scope	Docs
`GET`	`/conversations`	`comms_read`	List

Webhooks

Method	Path	Scope	Docs
`GET`	`/webhooks`	`comms_webhooks`	List
`POST`	`/webhooks`	`comms_webhooks`	Create

Events

Method	Path	Scope	Docs
`GET`	`/events`	`comms_read`	List

AI

Method	Path	Scope	Docs
`POST`	`/chat/completions`	`comms_ai`	Chat completions
`GET`	`/ai/usage`	`comms_ai`	AI usage
`GET`	`/ai/models`	`comms_ai`	AI usage

Lines

Method	Path	Scope	Docs
`GET`	`/lines`	`comms_lines_read`	List available lines
`POST`	`/lines/claim`	`comms_lines_write`	Claim a line

Rate limits

See Errors & rate limits. Defaults are roughly 100 requests/min globally and 60 sends/min per caller.

SDKs

There is no required SDK. Use any HTTP client with a Bearer token. The quickstart shows cURL, Node, and Python.

Line porting

Bring an existing number onto a dedicated Comms line with the Line Port API. Access requires permission — request access before use; it is not unrestricted self-serve porting. Contact your current carrier for port-out details; speed and success depend on an exact match to their records.

​Base URL

​Authentication

​Conventions

​Endpoint map

​Messages

​Conversations

​Webhooks

​Events

​AI

​Lines

​Rate limits

​SDKs

​Line porting