REST API

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/v1

The 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_here

Generate 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.

Product search

If Storefront Search is set up for a business, the same search pipeline is available over REST — for a storefront you render server-side, a mobile app, or anywhere our browser SDK doesn't fit. Five POST endpoints, each taking the business's businessSlug:

Every ranking endpoint answers with the same results array — { id, score, product }, where product is the untouched product object as ingested from your store feed. You render it with the fields you already have; we don't impose a product schema on you. Rate limits are per organization, and the business must belong to the organization the API key is scoped to.

A typed search:

curl https://api.octocom.ai/rest/v1/products/search \
  -H "X-API-Key: $OCTOCOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"businessSlug":"my-store","query":"black leather office chair","topK":20}'

Voice

Send one short recording — a single spoken query. This is not a streaming endpoint: detect end-of-speech on the client, then post the clip. The transcript is fed to the same pipeline as a typed query, so you get the transcript and its results in one round trip.

Audio goes in the audio field, base64-encoded (a data: URL works too), up to 1 MB decoded — about 15 seconds, far more than a search query needs. audio/webm, ogg, mp4, mpeg, wav, aac and flac are accepted.

curl https://api.octocom.ai/rest/v1/products/search/voice \
  -H "X-API-Key: $OCTOCOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg audio "$(base64 -i query.webm)" \
        '{businessSlug: "my-store", audio: $audio, mimeType: "audio/webm"}')"

{
  "data": {
    "transcript": "black leather office chair",
    "noSpeech": false,
    "language": "en",
    "results": [{ "id": "SKU-12345", "score": 0.83, "product": { "…": "…" } }],
    "relaxed": false
  }
}

• noSpeech: true means the recording carried nothing recognizable — a normal outcome, and answered as 200 with no results. Tell the shopper "didn't catch that" rather than "no products match".
• Language is detected between a small candidate set rather than freely, which is much more accurate on a three-word utterance. Omit language to use the business's configured voice languages; pass one code ("el") to state it outright, or a comma-separated list ("lt,en,ru") to detect between them. The language actually heard comes back in the response.
• Recognition is biased with your catalogue's own mined vocabulary, so brand and product names survive.
• Pass "mode": "transcribe" to get only the transcript and run the search yourself later — for a dictate-and-review flow where the shopper edits before submitting.
• Unlike the storefront widget's mic, this endpoint doesn't require the dashboard's Voice search switch. That toggle governs what shoppers get on your storefront; this surface is your own authenticated backend.

Image

The photo is read by a vision model whose understanding drives retrieval directly. Base64 in the image field (or a data: URL), up to 6 MB decoded, as image/jpeg, png, webp or gif. Downscale big photos to around 1024px on the long edge first — it costs nothing in quality and is most of the upload latency.

curl https://api.octocom.ai/rest/v1/products/search/image \
  -H "X-API-Key: $OCTOCOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg image "$(base64 -i chair.jpg)" \
        '{businessSlug: "my-store", image: $image, mimeType: "image/jpeg", query: "in blue"}')"

The optional query refines the photo ("in blue", "cheaper") rather than replacing it. The response adds saw — what the model read off the photo:

{ "data": { "results": [], "relaxed": false, "saw": ["office chair"] } }

Show saw to the shopper ("Showing results for: office chair"). A misread photo then reads as a misread instead of looking like an empty catalogue. This endpoint can't start retrieving until the photo is understood, so it's the slowest of the five.

saw is the item type read off the photo, not the query that was run: retrieval also uses the colour, material, size and setting the model read, which is what distinguishes the photographed product from the rest of its category. The full derived query is shown in the dashboard's Storefront Search preview if you need to debug a result.

Similar products

A "you may also like" row, keyed by the product's id as it appears in your feed — the same id the other endpoints return.

curl https://api.octocom.ai/rest/v1/products/search/similar \
  -H "X-API-Key: $OCTOCOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"businessSlug":"my-store","productId":"SKU-12345","topK":8}'

{
  "data": {
    "results": [{ "id": "SKU-67890", "score": 0.71, "product": { "…": "…" } }],
    "source": { "id": "SKU-12345", "name": "Aera Office Chair" }
  }
}

Results never include the source product, and are reranked using its own indexed type and category — which is what keeps a phone's cases out of its neighbours. source is null when the id isn't in the catalogue index; that's different from a product with no neighbours, and usually worth handling differently. Costing no model or embedding call, this is the cheapest of the five and safe to call on every product-page view.

Pagination, rate limits, and errors

• Pagination — list endpoints accept a page query 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:

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.