Reference

REST API

Create an API key under Account → API keys, then send it as Authorization: Bearer mc_sk_…. Your bot ids appear in each bot's dashboard URL. API access is an Agency plan feature.

Ask a question — POST /api/v1/query

curl -X POST https://app.matterchat.co/api/v1/query \
  -H "Authorization: Bearer mc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"botId": "YOUR_BOT_ID", "question": "Do you ship internationally?"}'

Response

{
  "answer": "Yes — we ship to most of Europe and North America...",
  "sources": [
    { "n": 1, "title": "Shipping & delivery", "url": "https://acme.com/shipping" }
  ],
  "grounded": true
}

grounded: false means nothing relevant was found. When that happens answer is null and sources is empty — no answer is invented to fill the gap. Treat it as a refusal and route it the way you would route one in the widget.

Add or refresh a page — POST /api/v1/ingest

curl -X POST https://app.matterchat.co/api/v1/ingest \
  -H "Authorization: Bearer mc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"botId": "YOUR_BOT_ID", "url": "https://your-site.com/new-page"}'

Response

{
  "sourceId": "src_...",
  "chunkCount": 12,
  "skipped": false,
  "error": null
}

skipped: true means the page content has not changed since the last ingest, so nothing was re-indexed. Calling this after a deploy is safe and cheap — unchanged pages cost nothing.