REST API
Programmatic access to your Octocom data and configuration over plain HTTP — list and read conversations, manage workflows, articles and bot rules, record purchases, and more. This page explains what the API covers and where to find the full reference.
Octocom exposes a REST API for reading your customer support data and managing your bot's configuration programmatically. It's the right choice when you want to pull data into your own systems, run scripts and scheduled jobs, or integrate Octocom from a backend service — anywhere a stable HTTP contract is easier to work with than MCP.
Looking for the full, interactive reference? Every endpoint — with parameters, request/response schemas, and a "try it" console — lives at api-docs.octocom.ai. This page is the orientation; that's the spec.
Base URL
All endpoints are served from production under the /rest/v1 prefix:
https://api.octocom.ai/rest/v1The machine-readable OpenAPI 3 specification is available at https://api.octocom.ai/openapi.json — point your own codegen, Postman, or client library at it.
Authentication
Every request (except the public Browser Sessions endpoint) authenticates with an API key sent in the X-API-Key header:
X-API-Key: your_api_key_hereGenerate and manage your key from the API Key page under Settings in your Octocom dashboard. The key is scoped to your organization — keep it secret and treat it like a password. You can regenerate it at any time from the same page, which immediately invalidates the old key.
A first request
List the most recent conversations:
curl https://api.octocom.ai/rest/v1/conversations \
-H "X-API-Key: $OCTOCOM_API_KEY"List endpoints are paginated and filterable. For example, fetch the second page of conversations that were closed in a given window:
curl -G https://api.octocom.ai/rest/v1/conversations \
-H "X-API-Key: $OCTOCOM_API_KEY" \
--data-urlencode "status=closed" \
--data-urlencode "startDate=2026-01-01T00:00:00Z" \
--data-urlencode "endDate=2026-01-31T23:59:59Z" \
--data-urlencode "page=2"Conversations can also be filtered by handedOff state and by a metadataKey / metadataValue pair (e.g. to find the conversation tied to a specific Zendesk ticket). See the reference for the full set of parameters on each endpoint.
What you can access
The API is organized into resource groups. Most are read-only; the configuration resources (Workflows, Articles, Bot Rules) also support create / update / delete with version history and restore, mirroring what you can do in the dashboard.
| Resource group | What it covers |
|---|---|
| Conversations | List and read conversations with full message history, AI classifications, and agent notes. Add tags and events, set metadata, and send outbound email. |
| Customers | List customer profiles and contact info; update a customer and set customer metadata. |
| Custom Data | AI-classified data extracted from conversations, for analytics and reporting. |
| Businesses | List the businesses in your organization (use their slugs when calling business-scoped endpoints). |
| Users & Teams | List the team members, agents, and team structure in your organization. |
| Macros | Response templates used by human agents. |
| Workflows | Manage the multi-step playbooks that guide the bot — create, update, delete, list version history, and restore. |
| Articles | Manage knowledge base articles the AI answers from — full CRUD with versioning and soft-delete / restore. |
| Bot Rules | Manage the custom instructions that steer bot behavior — full CRUD with versioning and restore. |
| Bot Conversations | Start a conversation with the bot and send it messages programmatically (useful for automated testing or embedding). |
| Google Sheets | Append rows to a Google Sheet (share the sheet with the service account shown in the reference as an editor). |
| Browser Sessions | Record a purchase against a browser session for custom sale attribution. No API key required — rate limited by IP. |
Pagination, rate limits, and errors
- Pagination — list endpoints accept a
pagequery parameter (1-based). - Rate limiting — requests are rate limited; exceeding the limit returns
429 Too Many Requests. Back off and retry. - Errors — the API uses standard HTTP status codes:
| Status | Meaning |
|---|---|
200 | Success |
401 | Invalid or missing API key |
404 | Resource not found |
429 | Rate limit exceeded |
500 | Server error |
REST API vs. MCP
Octocom offers two programmatic surfaces, and they're complementary:
- REST API — a fixed, versioned HTTP contract. Best for backend integrations, data pipelines, scheduled jobs, dashboards, and anything you want to script deterministically.
- MCP — the same capabilities (and more) exposed to AI agents like Claude and ChatGPT, so an agent can configure, debug, and test your bot in natural language. Best for hands-on, exploratory, and "do this for me" work.
If you're writing code, start with the REST API. If you're driving an AI agent, use MCP.
Need access or help?
API keys are available from the dashboard today. If anything in the reference is unclear or you need an endpoint that isn't there yet, reach out — we're expanding the API and use your requests to prioritize.