API conventions

Base URL

Environment	Origin
Hosted	https://api.inside.chat
Local development	http://localhost:8787

Every REST path starts with /api/v1. The OpenAPI 3.1 document is served without authentication at GET /api/v1/openapi.json, and you can download it here.

Requests

• Send the token as Authorization: Bearer <token>.
• Send JSON bodies with Content-Type: application/json.
• Unknown, duplicate or unsupported parameters are rejected with 400. That keeps mistakes visible instead of silently ignored.

Websites

• Collection operations, such as GET /api/v1/conversations, need an explicit website_id query parameter. There is no default website.
• A resource ID already identifies its website. If you also send website_id, it must match.
• A resource you aren’t allowed to see returns 404, the same as one that doesn’t exist.

See identifiers for the format of every ID.

Pagination

• limit is 1 to 100 and defaults to 25, unless an operation says otherwise.
• Pass next_cursor from the previous response as cursor. A null next_cursor means there are no more pages.
• Pages can contain fewer items than limit, because responses are also capped at 256 KiB. Keep going while next_cursor isn’t null.
• Pages reflect current stored data. They aren’t a snapshot, so records can change between pages.
• Treat cursors as opaque, and reuse them only with the same filters.

Coverage

Many responses include a coverage label that says where the data came from, for example persisted_conversations or persisted_public_messages. The API returns stored data. Live, unsaved state, such as a chat in progress, isn’t included.

Tip

When you show Gateway data to people, mention the coverage. “Stored conversations” and “all conversations” aren’t the same thing.

Rate limits

Each application has per-minute and per-day request quotas, shared by REST, MCP and A2A. A separate per-network limit also applies. When a limit is reached, the API returns 429 with a Retry-After header in seconds. Don’t retry before it elapses.

Current authority

Every call checks the current credential, installation, application, organization, website grant and data policy. Revoking or narrowing access takes effect on the next call.

Public discovery endpoints

These endpoints need no credential and return no customer data.

Path	Content
/api/v1/openapi.json	The REST contract
/llms.txt, /llms-full.txt	Short and full Markdown guides for AI tools
/.well-known/oauth-authorization-server	OAuth endpoints, grant types and supported scopes
/.well-known/oauth-protected-resource	REST resource metadata
/.well-known/oauth-protected-resource/mcp	MCP resource metadata
/.well-known/oauth-protected-resource/a2a	A2A resource metadata
/.well-known/agent-card.json	A2A agent card
/version.json	The deployed Gateway build