API reference

The canonical machine-readable contract is OpenAPI JSON. This page is the human-readable operation index and explains rules shared by every endpoint.

Base URL and version#

https://makeagent.fast/api/v1

The major version is part of the path. Additive fields can appear without a major-version change, so ignore unknown response fields. All management requests use HTTPS and a bearer API key or OAuth access token.

Common headers#

Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-key

Content-Type is required for POST and PATCH JSON bodies, including {}. Idempotency-Key is optional but strongly recommended for every POST, PATCH, and DELETE.

Account and sites#

Creating a site requires title and content.headline. Optional fields include slug, type, template, additional content, persona_mode, and one to four languages from en, ko, uz, and ru.

PATCH /agent runs model, appearance, embed_chrome, and badge_hidden through the same plan checks as the dashboard; badge_hidden: true needs an eligible plan or the badge add-on.

Install and website widget#

Knowledge and FAQs#

POST /knowledge accepts three bodies: { "name", "text" } with 5–200,000 characters; { "url", "max_pages", "refresh_hours" } to crawl a website (max_pages 1–40, refresh_hours 1–8,760 or null); and { "kind": "youtube" | "podcast" | "feed", "url", "refresh_hours" }. YouTube, podcast, and feed sources need Operate or Scale; on Launch they return 409 conflict. File upload stays a dashboard workflow.

Conversations, leads, analytics, and usage#

These event and activity collections accept limit and cursor. Returned records can contain personal data; store and export them according to your privacy obligations.

Owner replies are supported: reply, pause, and resume take over a web thread or a Telegram, WhatsApp, Messenger, or Instagram chat the same way the dashboard does. Sending messages as the visitor is not a public API operation. Lead mutation is supported; do not set consent_status: granted unless your system has a defensible consent record. Unknown consent is excluded from broadcasts.

Opportunity pipeline and CRM outcomes#

The supplied CRM provider, external ID, and idempotency key remain in the audit trail. A retry claims only a failed record and never turns an in-progress external write into a false success.

Connectors#

Connector creation uses a channel-discriminated body. Credential fields differ for telegram, whatsapp, messenger, instagram, discord, and kakao; use the matching connector guide before sending secrets.

Broadcasts, notifications, and monetization#

Broadcast creation currently accepts only the kakao channel. Queueing fails with 409 conflict when there are no reachable recipients or the broadcast is no longer a draft.

Actions, tickets, and team#

Developer webhooks and setup tools#

Webhook URLs must use HTTPS, cannot include credentials or a custom port, and must resolve only to public IP addresses.

Pagination#

Paginated collections accept limit from 1 to 100; the default is 50. Use the returned opaque next_cursor only with the same collection and filters.

{
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Some small configuration collections return the same envelope with has_more: false and do not need a cursor.

Idempotency#

An idempotency key must contain 8–200 characters from letters, numbers, ., _, :, and -. Results are retained for 24 hours and scoped to the credential owner.

• Same key and same method, path, query, and body: returns the stored response with x-idempotent-replayed: true.
• Same key with different input: returns 409 conflict.
• Same key while the first request is processing: returns 409 conflict and Retry-After: 2.

Persist the key before sending the mutation and reuse it only for retries of that logical operation.

Responses and errors#

Success responses wrap their resource in data. Create operations normally return 201; queued broadcast sends return 202; other successful operations return 200. Every response includes x-request-id and uses Cache-Control: no-store for API data.

See Scopes and errors for the complete error-code table and API recipes for copyable workflows.

MCP clients#

Connect a Streamable HTTP MCP client to https://makeagent.fast/api/mcp. Clients supporting OAuth discovery open the browser for sign-in and consent. Verify the client identity, company and requested scopes before approving. The first approval asks for the scopes the tools use (sites:read, sites:write, agents:write, analytics:read, conversations:read, conversations:write, leads:read, leads:write, knowledge:write); a credential missing one of them is asked to authorize again. An active plan is required.

For clients using manually configured credentials, create a scoped API key in Developer settings and supply it as an Authorization: Bearer ... header. Keep credentials out of source control and browser code. Revoke API keys or OAuth grants from Developer settings.

Read tools: list_agents, get_agent, get_report, list_unanswered_questions, list_conversations, get_conversation, list_leads. Write tools: create_agent_from_website, create_agent_from_notes, test_agent, add_knowledge, save_answer, reply_to_customer, update_lead, set_website_widget. Every agent tool takes an agent_id from list_agents. test_agent spends credits like a normal answer; reply_to_customer sends a message to the customer and pauses the agent on that conversation; set_website_widget turns the website chat widget on or off; messaging channels are managed in the dashboard. Clients with MCP Apps enabled (by default the authenticated Claude connection) also get list_pending_approvals, list_action_runs, and decide_approval, which approves or declines a customer-confirmed change; other clients see only the 15 tools above. For the setup and GitHub integration tools, use the in-app setup helper or /api/v1/setup/tools.

Supported protocol revisions are 2026-07-28, 2025-11-25, and 2025-06-18. The transport returns JSON; it does not offer legacy SSE or server sessions. MCP OAuth tokens only authorize /api/mcp, not direct REST requests. OAuth access tokens last one hour; refresh credentials rotate and expire after 90 days. Manually created API keys use their configured expiry.