API & Agents overview
Access bots, knowledge, chat, conversations, leads, analytics and bookings through a scoped REST API or hosted MCP server. Available with live Growth or higher API access.
On this page
Offering bots to customers from an enterprise application? See the separate API Vendor guide for customer authorization and sponsored bots.
Authentication
Create a token in Dashboard → API & Agents. Tokens are scoped, can be limited to specific bots, and can expire. The token secret is shown once. Only workspace owners and admins can manage tokens or approve MCP OAuth access. Pass a token as a bearer header:
curl https://api-uat.famysync.com/v1/bots \ -H "Authorization: Bearer mgpt_your_token_here"
Keep tokens on your server. Browsers cannot call the token endpoints (they send no CORS headers), so a token in a web page does not work. To call a bot from your own web page, use its public key (see below).
REST and MCP access requires API access on an active paid Growth or higher plan, or an active Growth trial. Enterprise contracts must include API access. Tokens and OAuth connections stop working while the workspace is not live; restoring access does not require replacing the token.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /v1/bots | bots:read | List bots |
| POST | /v1/bots | bots:write | Create a bot (plan-limited) |
| GET | /v1/bots/{id}/settings | bots:read | Instructions, persona, fallback message and language settings |
| PATCH | /v1/bots/{id}/instructions | settings:write | Replace instructions, persona and/or fallback message (returns the previous text) |
| GET | /v1/kb?chatbotId=… | kb:read | List knowledge-base documents (limit/offset, status, type, q) |
| POST | /v1/kb/ingest | kb:write | Add knowledge from a URL or raw text (queued) |
| DELETE | /v1/kb/{id} | kb:write | Delete a knowledge-base document |
| GET | /v1/custom-answers | kb:read | List custom answers |
| POST | /v1/custom-answers | kb:write | Add a custom answer (queued) |
| PATCH | /v1/custom-answers/{id} | kb:write | Change a custom answer |
| DELETE | /v1/custom-answers/{id} | kb:write | Delete a custom answer |
| POST | /v1/chat | chat:invoke | Chat with a bot — SSE stream or one JSON reply, counts toward quota |
| POST | /v1/public/chat | public key | Chat from your own web page with a public key (mpk_…) |
| GET | /v1/conversations | conversations:read | List conversations (?q= search, ?channel=) |
| GET | /v1/conversations/{sessionId} | conversations:read | Full transcript of one session |
| GET | /v1/leads | leads:read | List intent-scored leads (?chatbotId= filter) |
| GET | /v1/analytics | analytics:read | 30-day analytics summary |
| GET | /v1/bookings | bookings:read | List appointment requests (?status= pending|confirmed|rejected|cancelled) |
| GET | /v1/bookings/{id} | bookings:read | One booking — visitor, slot, status |
| PATCH | /v1/bookings/{id} | bookings:write | Confirm, reject, reschedule, or cancel — emails the visitor |
| GET | /v1/openapi.json | — | This API as an OpenAPI 3.1 spec (no auth) |
Full schemas: openapi.json
A token restricted to specific bots must pass an allowed chatbotId for knowledge, chat, leads and analytics requests. Bot-restricted tokens cannot create bots. Enterprise bot creation requires enterprise_plan_tier (starter, growth or scale) and an available slot of that tier. Knowledge ingestion checks the bot's page quota before queuing.
Chat
POST /v1/chat returns Server-Sent Events: the reply text as OpenAI-style chunks, then an event: done with sessionId, sources (pages the reply is based on), suggestions (follow-up questions) and actions (handoff, askContact, offerBooking), then data: [DONE]. Pass "stream": false to get the same as one JSON object with answer.
Every message is saved as a conversation (channel api) and counts toward your quota. Without sessionId a new conversation starts; its id comes back in the X-Session-Id header and the done event. Pass it back to continue.
curl https://api-uat.famysync.com/v1/chat \
-H "Authorization: Bearer mgpt_…" \
-H "Content-Type: application/json" \
-d '{"message":"What is your refund policy?","chatbotId":"…","sessionId":"user-42","language":"ja-JP","stream":false}'
# → {"data":{"sessionId":"user-42","answer":"…","sources":["https://…"],"suggestions":["…"],"handoff":false,"askContact":false,"offerBooking":false}}Chat from your own web page
Create a public key (mpk_…) for a bot in Dashboard → API & Agents. It can only chat with that bot — it cannot read conversations, leads or settings — and works only from the bot's allowed domains, which must be switched on. Send it in the X-Famysync-Key header to POST /v1/public/chat; the request and reply are the same as /v1/chat without chatbotId. It is rate limited per key and per visitor, and messages count toward your quota.
const res = await fetch('https://api-uat.famysync.com/v1/public/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Famysync-Key': 'mpk_…' },
body: JSON.stringify({ message: 'Hello', sessionId, stream: false }),
})
const { data } = await res.json() // data.answer, data.sources, data.suggestionsBookings
List appointment requests and confirm, reject, reschedule, or cancel them. Confirming emails the visitor and blocks that slot. Reschedule needs requestedSlot (ISO-8601 with offset) and emails the new time. Cancel emails the visitor. Same behaviour as the Bookings page. Scopes: bookings:read / bookings:write.
curl https://api-uat.famysync.com/v1/bookings?status=pending \
-H "Authorization: Bearer mgpt_…"
curl https://api-uat.famysync.com/v1/bookings/BOOKING_ID \
-X PATCH \
-H "Authorization: Bearer mgpt_…" \
-H "Content-Type: application/json" \
-d '{"action":"confirm"}'
curl https://api-uat.famysync.com/v1/bookings/BOOKING_ID \
-X PATCH \
-H "Authorization: Bearer mgpt_…" \
-H "Content-Type: application/json" \
-d '{"action":"reschedule","requestedSlot":"2026-08-20T15:00:00+05:30"}'
curl https://api-uat.famysync.com/v1/bookings/BOOKING_ID \
-X PATCH \
-H "Authorization: Bearer mgpt_…" \
-H "Content-Type: application/json" \
-d '{"action":"cancel","cancelComment":"We need to close that day."}'MCP server (for AI agents)
Famysync hosts a remote MCP server, so Claude and other MCP-capable agents can list bots, add and delete knowledge, manage custom answers, change a bot's instructions, ask questions, read conversations, leads & analytics, and list / confirm / reject / reschedule / cancel bookings. Connect through user-approved OAuth or a scoped API token; one connection covers one workspace. Tools: list_bots, list_knowledge, add_knowledge, delete_knowledge, list_custom_answers, add_custom_answer, update_custom_answer, delete_custom_answer, get_bot_settings, update_instructions, ask_bot, list_conversations, get_conversation, list_leads, get_analytics, list_bookings, get_booking, update_booking.
{
"mcpServers": {
"Famysync": {
"url": "https://api-uat.famysync.com/mcp",
"headers": { "Authorization": "Bearer mgpt_…" }
}
}
}Get an API key in 2 minutes
Start the free trial, open Dashboard → API & Agents, create a token.
Start free trial