REST API v1

Everything on this page, as an OpenAPI 3.1 document: https://sumgenius.ai/api/v1/openapi.json. No key needed. Every endpoint, parameter, field, and allowed value is in it, including the scope each endpoint needs and the full list of webhook event names.

Give that URL to an SDK generator, an API client, or an AI assistant and it has the complete contract. The enums in it are generated from the same constants the API validates against, so they cannot drift from what the API accepts.

This page is also available as Markdown at /docs/rest-api.md.

Using an AI assistant instead of writing code? The MCP server wraps this API as 50 tools for Claude, Cursor and any MCP client.

Every request is authenticated with your API key from the portal's Webhook & Send API page. The same key opens the REST API, the Send API, and webhooks. Send it as any one of three headers; X-SumGenius-Api-Key is preferred.

The API is server-to-server. CORS is intentionally disabled, so call it from your backend and keep the key out of browsers.

• 401 unauthorized

  No API key sent.

• 401 invalid_api_key

  Key not recognized.

• 403 addon_inactive

  Key is valid but the add-on is not active.

The HTTP status carries success or failure. A single resource arrives as {"data": {...}}; a list adds has_more and next_cursor. Errors carry a stable code to branch on; message is human-facing and may change.

Lists are newest-first and cursor-paginated: pass limit (1 to 100, default 25) and feed next_cursor back as starting_after until has_more is false. Tags and team return their whole set in one page.

Send an Idempotency-Key header on any POST, PATCH or DELETE and a retry of the same request returns the same response instead of running twice. Use it whenever a network failure would leave you unsure whether the first attempt landed: creating records, sending messages, and later, bookings and posts.

• Idempotency-Keyheader, 1 to 128 printable characters

  Any string unique to the operation on your side, for example your own order or job id, or a UUID. Keys are scoped to your account and remembered for 24 hours.

• Replay

  A retry with the same key and the same method, path and body gets the original status and body back, with the header Idempotent-Replayed: true. Both successes and 4xx errors are replayed. A 5xx is never stored, so the same key can be retried after a server fault.

• Conflict

  The same key with a different body, path or method is 422 idempotency_key_reused. A retry that arrives while the first request is still running is 409 idempotency_in_progress with Retry-After.

POST /messages also accepts idempotency_key in the body, which the send engine deduplicates on its own. The header works there too, and using both is harmless.

Each account may make up to 200 authenticated REST requests per minute, with short bursts of up to 20 requests per second. All active API keys for the account share the same quota, so creating another key does not increase it.

The per-minute quota is measured over a rolling 60-second window rather than a fixed clock minute, so capacity returns gradually as individual requests age out instead of all at once on a boundary.

A separate system-wide safety ceiling protects API availability during aggregate traffic spikes. When either ceiling is reached, the API returns 429 rate_limited. Wait for Retry-After before retrying; use exponential backoff rather than an immediate retry loop.

Every authenticated REST response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Reset is a Unix timestamp. The equivalent X-RateLimit-* headers are also sent for compatibility.

This quota controls requests accepted by /api/v1. Message platforms enforce their own separate, account-specific delivery limits; temporary platform throttles continue through the existing queue and retry behavior.

• timestampsUTC ISO-8601

  Everywhere, e.g. 2026-07-25T04:35:23+00:00. The updated_since filters accept the same format.

• channelenum

  facebook · instagram · sms · telegram · whatsapp

• stageenum

  new · contacted · qualified · customer · lost

• statusenum

  active · resolved · pending · archived · escalated (conversations)

• custom_fieldsobject

  Your own per-contact data, as {field_key: value}. Only fields that are set and active appear; unset fields are omitted, never null. Define fields with POST /custom-fields, write values through PATCH /contacts/{id}.

Your account identity, plan, and configured webhook endpoints. A good first call to verify a key works.

An endpoint is a URL you own that receives events. Up to three per account. Each has its own signing secret.

Create body

• name · urlrequired

  url must be https on a public host.

• eventsarrayoptional

  Event names to deliver. [] or omitted means every event. Names come from the events reference or x-webhook-events in the OpenAPI document.

• governanceobjectoptional

  The data-sharing declaration: attested, purpose (at least 8 characters), destination_owner, payload_profile (full carries message text, minimal omits it). Partial on PATCH.

Going live is a separate step. An endpoint is created paused. PATCH {"enabled": true} turns it on, and is refused with 422 governance_incomplete until the declaration is attested with a purpose. Pausing stops new events from queueing; anything already queued waits and delivers when you enable it again.

Secrets. signing_secret is returned once on create and once on rotate, never on read. After a rotation the previous secret keeps verifying for about 24 hours.

Test. POST …/{id}/test with {"channel": "meta"} queues a sample event and delivers it right away, paused or not. delivered tells you whether your server answered 2xx.

Up to ten active keys per account. The list shows every key with a preview and its scope; is_current marks the one making the call. Key material is never listed.

Create takes name and scope (read by default). The plaintext comes back once as api_key. A key can mint keys up to its own reach: a full key can mint any scope, an admin key can mint read, write or admin.

Revoke stops the key at once. A key cannot revoke itself (409 cannot_revoke_self); use another key or the portal.

List contacts, newest first. Filters combine with AND. An invalid filter value returns 400 invalid_param.

Query parameters

• channelenumoptional
• stageenumoptional
• tagstringoptional

  Exact tag name; contacts carrying that tag.

• emailstringoptional

  Exact match.

• phonestringoptional

  Exact match.

• namestringoptional

  Substring match on the display name.

• updated_sincetimestampoptional

  Contacts updated at or after this time.

• limit · starting_afterpaginationoptional

One contact by id, in the same shape as the list. A non-numeric, unknown, or unowned id returns 404.

Create or update a contact by its natural identity. A new identity returns 201; an existing one is updated and returns 200. Updates are partial: omitted fields are untouched and existing tags are kept (tags adds, it does not replace).

Body

• channelenumrequired
• platform_user_idstringrequired

  The person's id on that channel, 1 to 255 characters. For SMS this is the phone number.

• namestringoptional

  Up to 255 characters.

• emailstringoptional

  Valid email address.

• phonestringoptional

  Digits and + ( ) . - # x, 3 to 50 characters.

• stageenumoptional
• notesstringoptional

  Up to 5,000 characters.

• tagsstring[]optional

  Tag names; missing tags are created automatically.

• custom_fieldsobjectoptional

  Merged into the contact's fields, applied atomically with the rest of the upsert. Same semantics as PATCH. Fields must already be defined.

Partial update by id. Only fields present in the body change. Send "" to clear a field. Idempotent by nature, so no idempotency key is needed. An empty body returns 400 listing the updatable fields.

Body · all optional

• stageenum
• namestring

  Up to 255 characters, or "" to clear.

• emailstring

  Valid email, or "" to clear.

• phonestring

  3 to 50 characters, or "" to clear.

• notesstring

  Up to 5,000 characters, or "" to clear.

• custom_fieldsobject

  Merge semantics: only the keys you send change, null as a value clears that field, other fields are untouched. Values are validated against each field's type (400 names the offending key). Every actual change fires a contact.field_changed webhook event.

Attach a tag by name. A tag that does not exist yet is created, then attached. Re-attaching is a no-op 200. Returns the updated contact.

Body

• namestringrequired

  1 to 50 characters. Created if missing, with the default color.

Detach a tag from a contact. {tag} is a tag id or a URL-encoded name; a name that is all digits or contains / must go by id. Detaching a tag the contact does not have is an idempotent 200; a tag that does not exist at all is 404. Only the attachment is removed; the tag itself survives.

Permanently erases a person: the contact and every conversation, message, and appointment they have. Built for right-to-erasure requests.

Tag definitions and send-history audit records survive. Repeating the call is a safe 404.

Your field definitions, in creation order. Active fields only by default.

Query parameters

• include_archivedbooleanoptional

  Also return archived definitions (with archived true) so their ids stay discoverable for unarchiving.

Define a field. Returns 201 on create, 200 if an equivalent field already exists (same key and type), 409 if the key exists with a different type or archived, and 400 at the 15-active-field limit.

Body

• field_keystringrequired

  1 to 50 characters of a-z 0-9 _. Permanent after create, it is the JSON key in every payload.

• labelstringrequired

  Display name, 1 to 100 characters. Renameable later.

• typeenumoptional

  text (default, up to 500 chars) · number · date (YYYY-MM-DD) · boolean. Permanent after create.

Rename a field's label, or archive / unarchive it. field_key and type are immutable, sending either returns 400. There is no delete: archiving hides a field from every surface without touching any contact data, and unarchiving restores it (subject to the 15-active limit).

Body

• labelstringoptional
• archivedbooleanoptional

  true hides the field everywhere; false restores it, values intact. Writes to an archived field's values return 400.

List conversations, newest first. contact_id links each thread to its person.

Query parameters

• channelenumoptional
• statusenumoptional
• assigned_tointegeroptional

  A team member id from team.

• updated_sincetimestampoptional
• limit · starting_afterpaginationoptional

One conversation by id, in the same shape as the list. A non-numeric, unknown, or unowned id returns 404.

Change a conversation's status, or take it away from the AI and hand it back. Two optional fields, send one or both. Returns the conversation, which now carries ai_paused and ai_pause_reason so you can see the effect. Needs the write scope.

• statusstringoptional

  active, resolved or archived. Resolving or archiving hands the thread back to the AI, exactly like the inbox. pending and escalated are set by the system and cannot be sent.

• ai_pausedbooleanoptional

  true takes the thread away from the AI as the account owner, the inbox Claim button. It reopens a resolved thread. Refused with 409 when the customer is blocked, has opted out, or the Meta messaging window has closed. false hands the thread back to the AI, the inbox Transfer to AI. Refused with 409 resume_blocked when the pause came from a solicitation pause, a fraud flag or a connected-account pause; those are lifted in the portal only.

• ai_pause_reasonin the response

  escalated, assigned, owner_claimed, solicitation, fraud, connected_account, or null when the AI is live. The AI is muted on any thread that is assigned or escalated; this field tells you which.

Status is applied first, then ai_paused. Fires conversation.resolved and conversation.assigned as appropriate.

Assign or unassign a conversation, exactly like the inbox does it: a pending or escalated thread becomes active, history is recorded, and a system line is added to the transcript. Returns the updated conversation.

Body

• assigned_tointeger | nullrequired

  A team member id from team, or null to unassign. An unknown id is 400.

Permanently deletes one conversation: the full transcript, in-chat appointments, tag labels, and assignment records.

The response counts what was removed. Analytics rows are kept but stripped of message text and unlinked; send-history audit survives. A repeat delete is a safe 404.

The transcript of one conversation, newest first (default limit 50). Copilot drafts are excluded; this is the conversation as the customer saw it.

• directionderived

  user is inbound; bot, agent, followup are outbound; the rest is system.

• typeenum

  text · image · video · audio · file · quick_reply · button · postback · comment_trigger

• body_purgedboolean

  When a body was purged for compliance, text is null and this is true; the message is still listed.

Send on any channel. Same engine as the Send API with full parity; recommended for new integrations. Route by conversation_id, by platform + platform_user_id, or by to_phone for SMS and WhatsApp. To reply privately to an Instagram or Facebook comment (with optional buttons), add comment_id, full reference under private reply; the body is identical here.

Body

• idempotency_keystringrequired

  Your unique key per send. A replay returns the original result without resending. Also accepted as an Idempotency-Key header.

• actionenumoptional

  send_message (default) · react · unreact · typing_on. Support varies by channel.

• conversation_idinteger

  Route by an existing thread.

• platform + platform_user_idstring

  Route by the person's channel id.

• to_phonestring

  Route by phone (SMS, WhatsApp).

• message_textstringrequired

  Not required for typing_on or WhatsApp template sends (template_name, template_language, template_components).

Cold outbound

SMS, WhatsApp, and Telegram may send to a recipient with no existing conversation; the thread is created automatically. Facebook and Instagram require the customer to message first.

Send errors

All tag definitions, ordered by name, in one page. name is what the contacts ?tag= filter matches.

Create a tag definition. Idempotent on name: new returns 201, existing returns 200 with its color unchanged.

Body

• namestringrequired

  1 to 50 characters, unique per account.

• colorstringoptional

  6-digit hex like #FF0000; anything else is 400.

Deletes a tag definition account-wide and removes it from every contact and conversation carrying it. By numeric id only.

List bookings, newest first.

Query parameters

• statusstringoptional

  Exact match, e.g. confirmed or cancelled. Free text: an unknown value returns an empty list, not 400.

• conversation_idintegeroptional
• limit · starting_afterpaginationoptional

One appointment by id, same shape as the list. Unknown or unowned id returns 404.

The open slots for one day: business hours minus existing bookings, stepped by the service duration plus the buffer, and never sooner than the minimum notice. Exactly what the booking bot offers and the portal picker shows. An empty list means the day is closed or full.

• dateYYYY-MM-DDrequired

  In the account timezone, returned as timezone.

• service_typestringoptional

  A bookable service name (see booking.bookable_services on /ai/config). Sets the slot length; unknown or omitted means 30 minutes.

• city · statestringoptional

  Location-specific availability for multi-location accounts.

Book a slot. Same engine as the portal calendar and the bot: the account's required customer fields are enforced, the time must be in the future and free, the appointment is confirmed at once, it is synced to Google Calendar and GoHighLevel when connected, and appointment.booked fires. Needs the write scope.

• date · timeYYYY-MM-DD · HH:MMrequired

  The customer's wall-clock time in timezone (the account timezone when omitted). Use a time from availability.

• customerobjectrequired

  {name, email, phone, address}. name is always required; the rest follow the account's booking.required_fields. Missing ones are 422 missing_fields with the list.

• conversation_idintegeroptional

  Book for the person you are chatting with. Sets the channel, links the contact, and sends them the confirmation DM unless send_confirmation is false. Without it the booking is a walk-in with no DM.

• service_type · duration_minutes · location · vehicle_info · cost · notesoptional

  duration_minutes defaults to the service's duration from the service menu, else 30.

A taken or out-of-hours slot is 409 slot_unavailable. A past time is 400.

Edit details and/or status, the portal's edit form. Send only what changes: customer, location, service_type, duration_minutes, timezone, vehicle_info, cost, notes, status (pending, confirmed, completed, cancelled, no_show). Detail edits are pushed to the connected calendars; a status of cancelled removes the calendar event and fires the cancelled event. To move the time use reschedule, which checks the slot; this endpoint does not take a date.

The response carries sync_warning: true when a connected calendar refused the change. The appointment itself was saved.

Sets the status to cancelled, removes the Google Calendar and GoHighLevel events, and fires appointment.cancelled. 409 already_cancelled if it already is. Send {} as the body. The row is kept; there is no delete.

Moves a pending or confirmed appointment to a new date and time (in the appointment's timezone) after checking the slot is free, updates the connected calendars, and fires appointment.rescheduled. When the booking came from a conversation the customer is told in the DM, like the bot does. 409 slot_unavailable when the slot is taken, 409 not_active when the appointment is cancelled, completed or a no-show.

List flows, newest first.

Query parameters

• statusstringoptional

  draft, active or paused.

• trigger_typestringoptional

  keyword, first_message, comment_trigger or button_tap.

• limit · starting_afterpaginationoptional

Retrieve one flow. The list resource plus definition (the draft when one exists, otherwise the published version), has_draft, draft_behavior_changed, node_count and tag_id. 404 if it does not exist, was deleted, or belongs to another account.

The node catalogue: everything a definition may contain. Read it once before building a flow; it is the contract the validator enforces.

• definitionobject

  The shape of a definition and the structural rules (one trigger with id "1", every other node reachable, ports must exist, node cap).

• sourcesobject

  The 13 trigger sources keyed by name (dm, comment, story_reply, ai_intent, first_message...). Each has channels it can fire on, needs_keywords, and its config schema.

• nodesobject

  The 12 node types keyed by type. Each has inputs, outputs (the port names, or the rule that derives them: a message gets one port per postback button plus output_timeout; a condition gets one per rule plus a fall-through), terminal, a description, and a JSON-Schema-style config with required keys and enums.

• enums · placeholdersobject · array

  Every allowed value (channels, match types, input types, rule types, action types, delay units, HTTP methods, button and media types) and the {placeholders} a message may use.

• liveobject

  This account's options: custom_fields, tags, services (for book_appointment), other flows (for goto_flow), comment_triggers (for a linked comment source), plus node_limit, flow_limit and active_flows from the plan.

Check a definition without saving anything. Runs the same checks as create and update: structure, every node's config against the catalogue, channel compatibility with the trigger source, keyword collisions with your other active flows, and references (tag ids, custom field keys, service ids, target flows, comment triggers) against this account. Always 200; read valid.

Body

• definitionobjectrequired

  {trigger, nodes, edges}. See the example under create.

• channelsarrayoptional

  Where the flow will run: facebook, instagram, whatsapp. Defaults to facebook and instagram.

Create a flow as a draft. Nothing runs until you publish or activate it. Returns the flow with 201 and any warnings; a definition with errors is refused with 422 invalid_definition and the same errors list validate returns. 403 plan_limit_reached when the plan's flow count is full.

Body

• namestringrequired

  Up to 100 characters.

• definitionobjectrequired

  trigger: the trigger config (source plus that source's keys: keywords and match_type for dm, comment_trigger_id or comment_keywords for comment, intent_description for ai_intent...). nodes: [{id, type, config}], ids are strings and the trigger is "1". edges: [{from, from_port, to}]; from_port defaults to output_1.

• channelsarrayoptional

  Defaults to facebook and instagram. Must be channels the trigger source can fire on.

• tag_idintegeroptional

  Tag applied to everyone who enters the flow. One of live.tags.

Update name, channels, tag_id or definition. Sending a definition saves it as the flow's draft: the published version keeps running until you publish. A definition replaces the whole graph; send the complete one. The same validation as create applies (422 invalid_definition). GET /flows/{id}/definition returns {flow_id, has_draft, definition} on its own, the draft when one exists.

The builder's buttons. Each POST takes an empty JSON body ({}) and returns the flow.

• publish

  Makes the draft the live definition and bumps published_version. A draft flow goes active when the plan's active-flow cap allows; otherwise it stays published but paused. A comment flow linked to a comment trigger goes live with that trigger.

• activate

  Sets the flow live, publishing the draft first when there is one. 403 plan_limit_reached at the active-flow cap; 422 invalid_definition when the draft has errors or its keywords collide with another active flow; 409 flow_blocked for anything else the builder would refuse.

• pause

  Stops the flow and cancels anyone mid-session. Only an active flow can be paused (409 not_active). Pausing a linked comment flow pauses its comment trigger too.

• discard-draft

  Throws away unpublished changes; the published definition stays.

• duplicate

  Copies the flow as a new draft named "... (Copy)". 201 with the copy.

• DELETE

  Deletes the flow for good: its versions go with it and anyone mid-session is dropped. A linked comment trigger is paused, not deleted. 200 {"deleted": true}.

Publishing, activating and pausing fire flow.published, flow.activated and flow.paused whether done here or in the portal.

List sessions, newest first.

Query parameters

• flow_idintegeroptional
• statusstringoptional

  waiting_input, delayed, completed, expired or cancelled.

• channelstringoptional

  instagram, facebook or whatsapp.

• contact_idintegeroptional

  Every run by one person. An unknown contact returns 404 rather than an empty list, so a bad id cannot look like "no activity".

• updated_sinceISO-8601optional

  Sessions touched since this time. Use it to poll incrementally.

• limit · starting_afterpaginationoptional

Retrieve one session. Same resource as the list.

The ordered path through the flow, oldest first. Every step a person reached and every branch they took.

Query parameters

• typestringoptional

  One event type: session_started, node_entered, node_exited, branch_selected, input_received, link_clicked, outcome_achieved, session_completed, session_expired, session_cancelled, session_reactivated.

• limit · starting_afterpaginationoptional

  Default 100 here, and ordered ascending so pages read in sequence.

The same events, flat across every session. Use this one to analyse how a flow performs; use the nested route above when you want one person's path.

Query parameters

• flow_idintegeroptional
• flow_sessionintegeroptional

  One session's events, in the flat shape. Named flow_session rather than session_id because web application firewalls commonly block that parameter name outright. The field in the response is still session_id.

• typestringoptional

  Same event types as the nested route.

• node_keystringoptional

  One step of the flow. Combine with type=branch_selected to see every choice made at a single decision point.

• sinceISO-8601optional
• limit · starting_afterpaginationoptional

The builder's Analytics panel for one flow. Analytics are per published version: version defaults to the current one and versions[] lists the others, with has_tracked_runs so you know which are worth asking for. Only runs with journey tracking count; other_version_runs_excluded says how many runs in the window belong to other versions, and other_versions[] summarises them.

Query parameters

• rangestringoptional

  7d, 30d (default), 90d or all. comparison is null for all.

• channelstringoptional

  facebook, instagram or whatsapp.

• versionintegeroptional

  A published version from versions[]. 404 for a version the flow never had.

What comes back

• summary · comparison · lifetime

  Runs, completed, expired, cancelled, still active, completion rate and median seconds to complete for the window; the same for the previous window as deltas; and the flow's all-time counters across every version.

• outcomes

  What the runs produced: emails and phones collected, leads marked, appointments booked, links clicked, handoffs, custom fields saved. Each with a count, a rate against runs, and a median time to reach it.

• per_node · branches · nodes

  For every node of that version: how many runs reached it, continued past it, answered it, ended there and why (terminal_reasons), plus link clicks per button. branches gives the split per output port in the same order. nodes maps ids to types; the full definition is on GET /flows/{id}.

The numbers behind the portal's Overview page, from the same data layer: a rolling 30-day window against the 30 days before it. No parameters; the window is fixed like the page, and every count is a {current, previous} pair.

• messages

  Inbound, outbound and conversations touched, in total and by_channel.

• replies

  Outbound bot messages split into ai (written by the model) and automation (flows, comment triggers, welcomes).

• flows · comment_triggers

  Entries per flow and fires per standalone trigger, each with all_time. A comment trigger attached to a flow is the top of that flow's funnel, so its fires ride on the flow row as comment_trigger_fires and never appear as their own row. One comment is never counted twice.

• contacts · appointments · knowledge_gaps · needs_you · api_sends

  New contacts and totals with phone or email; appointments created, upcoming, and the next few; knowledge gaps by status; escalated conversations and Copilot drafts waiting; Send API requests this window.

• usage

  This billing cycle: conversations used against the plan cap, overage state, SMS used, and whether the account is on a trial. Account-level, never channel-scoped. null if the plan lookup fails, the way the page degrades.

List opt-outs, most recent first, across every channel.

Query parameters

• channelstringoptional

  instagram, facebook, whatsapp, telegram or sms.

• statusstringoptional

  opted_out or opted_in. Only SMS can be opted back in, so status=opted_in returns SMS records only.

• scopestringoptional

  comment_dm, broadcast or all. Meta channels only, so passing it excludes SMS.

• sinceISO-8601optional

  Filters on recorded_at, the same field the list is sorted by, so someone who opts back in today shows up in today's sweep even if their original opt-out was long ago. Use it to sync consent changes incrementally.

• limit · starting_afterpaginationoptional

An invitation is how someone joins: they get an email with a setup link, choose a password, and appear in GET /team. Pending invitations hold a seat against the plan cap until accepted, expired (7 days) or cancelled.

Create body

• emailstringrequired
• namestringrequired

  Used in the email greeting only. They set their own name when they accept.

• rolestringoptional

  agent (default) answers conversations. manager also gets the dashboard, leads, AI settings and content. Billing, team, integrations and keys stay owner-only.

• channelsarray or nulloptional

  Restrict them to some of facebook, instagram, whatsapp, sms, telegram. Omit for every channel.

403 plan_limit_reached when every seat is taken. 409 already_member or 409 invitation_pending for a known address. The setup link is never returned, except as invite_link when email_sent is false, so you can deliver it yourself.

Resend issues a fresh link (the old one stops working), resets the expiry and emails the reminder. Cancel removes the invitation and frees the seat.

PATCH changes role and/or channels (null for every channel). It takes effect at their next login, the same as the portal. Returns the member. DELETE removes them: their login stops at once and their conversations become unassigned. conversations_unassigned says how many. No event fires for that.

Your team members, ordered by name, in one page. A member's id is what assigned_to references and what assign accepts. Credentials and permission data are never exposed.

• roleenum

  agent · manager

• statusenum

  online · away · busy · offline

• channelsarray or null

  The channels this member can see. null means every channel.

Nine sections. available on file_handling, followups, csat and comment_ai tells you whether the plan includes that feature. Needs the read scope.

• identity

  name, tone (casual, professional, formal), instructions (up to 15,000 characters), instructions_source (auto or manual, read-only), welcome_message (up to 500), welcome_mode (combined or standalone), website_url, business_contact_email, business_contact_phone.

• behavior

  goals (any of answer_questions, book_appointments, capture_leads, qualify_prospects), batch_messages, batch_window_ms (minimum 5000), auto_escalation, copilot_enabled, business_hours (seven days, read-only for now).

• restrictions

  off_limits: legal, medical, competitors, pricing, personal, offtopic, each true or false. solicitation_pause.

• starters

  instagram.enabled and instagram.questions (up to 4, 80 characters each), facebook.enabled, facebook.mode (ice_breakers or get_started), facebook.questions. published carries when each platform was last published and any error, read-only.

• file_handling

  enabled (one switch for images, documents and videos), auto_escalate_on_image, auto_escalate_on_document, auto_escalate_on_video, escalate_if_team_online. Enabling it forces batching on.

• followups

  enabled, first_delay_minutes (5 to 60), second_delay_hours (1 to 23), quiet_hours.enabled, quiet_hours.start, quiet_hours.end (HH:MM).

• csat

  enabled, template (simple, friendly, professional, custom), custom_message (up to 500).

• comment_ai

  The AI Comment Manager, which handles comments no trigger claimed. enabled, mode (auto posts replies at once, approval queues them under /comments), instructions (up to 5000), reply_length (short, medium, detailed), moderation (spam, profanity, negativity, competitor_links, self_promotion, each true to hide), dm_on_hide and dm_message ({name} is the commenter), exclude_rules (a list of {type: post_id | keyword, value}, replaced whole). Pro plans and above.

• booking

  The Booking Configuration modal. enabled (AI Booking; off means the AI declines booking requests, the API and the portal can still book), google_meet_invites (needs Google Calendar connected, forces email to required), required_fields (name, email, phone, address, vehicle, cost, each true or false, plus address_parts {city, state, street}). Read-only alongside: timing (buffer, minimum notice, max advance, reminder hours, timezone), calendar (which provider is connected), and bookable_services (the service menu rows with a duration, managed under /knowledge/services).

Send any subset of sections, each with any subset of its fields. Everything you leave out keeps its current value. Returns the full configuration after the change. Needs the admin scope.

• Validation

  Same rules as the portal. Out-of-range values are clamped where the portal clamps them (welcome message, batch window, name) and rejected where the portal rejects them (instructions over 15,000 characters, follow-up delays, starters without questions, an unknown CSAT template). An unknown section or field is 400 invalid_param with param naming it.

• Plan gates

  file_handling, followups, csat and comment_ai return 403 feature_unavailable on a plan that does not include them. Check available on the GET first.

• Starters publish on save

  Changing starters publishes to Instagram and Facebook at once, exactly like the portal. A publish failure still saves locally and is reported in starters.published.*_error.

• What this never touches

  The AI on/off switch per channel. Saving configuration leaves those alone; see channel switches.

The on/off switches per channel. Four channels: meta (Facebook and Instagram share one switch), sms, whatsapp, telegram. For each: connected, whether the channel is set up on the account; ai_enabled, whether the AI answers customers on it; automation_enabled, whether flows and triggers run on it. Needs the read scope.

Switch the AI or automations on one channel. Send ai_enabled and/or automation_enabled as booleans. Returns that channel's state. Needs the admin scope. facebook and instagram are accepted as aliases of meta.

• Off always works

  Turning a switch off never fails. This is the call to make when the bot must stop answering right now.

• SMS AI on has two gates

  409 sms_not_ready until carrier registration assigns a Messaging Service to your number. 409 purge_active while inbound body purge is on in your webhook settings, because the purge clears the SMS context the AI needs. Turn the purge off first.

• What this never touches

  Any other setting. The AI configuration, external reply mode and the purge flag are separate.

Items against the plan cap, broken down by FAQs, services and documents, plus document storage. Check items.can_add before creating. Needs the read scope.

GET lists (active only unless include_inactive=true), POST creates, GET /{id}, PATCH /{id} and DELETE /{id} do what they say. Writes need the write scope.

• questionstring, up to 1,000required on create

  What a customer would ask.

• answerstring, up to 10,000required on create

  What the AI should say. Written in the bot's voice by the model, so plain facts work best.

• keywordsstringoptional

  Comma-separated hints that help matching. Empty string clears.

• activebooleanoptional

  Switch the FAQ off without deleting it. Changing only active does not re-index; changing content does.

Create returns 403 plan_limit_reached at the cap. Responses to create and update carry embedding_pending, true when indexing has not finished yet.

Same five operations as FAQs. A service is something the AI can quote and, with booking on, offer.

• namestring, up to 200required on create
• pricenumber, zero or morerequired on create

  Returned as a two-decimal string. price_unit is fixed, hourly, per_unit or quote. currency is an ISO 4217 code, or null for the account default.

• description · duration_minutes · display_order · category_id · activeoptional
• is_virtualbooleanoptional

  Bookings for this service get a Google Meet link. Honoured only when Google Calendar is connected and Meet is switched on; otherwise stored as false.

• image_urlread-only

  Service images are added in the portal. The API never changes or removes one.

Uploaded PDFs and text files. GET lists and GET /{id} reads metadata: name, type, size, embedding state. Content is never returned. PATCH /{id} takes name and active. DELETE /{id} removes the document and its embeddings.

There is no create. Uploading a document means parsing a file against a storage cap, which stays in the portal.

Questions the AI could not answer well. Each gap carries the customer's message, the AI's reply, a generic form of the question so repeats group together, how often it came up, and where the classifier thinks the fix belongs: a new FAQ or a line in the instructions. Open gaps by default. Needs the read scope.

Read-only on purpose. Fix a gap with POST /knowledge/faqs or by updating identity.instructions in the AI configuration. Dismissing stays in the portal.

Query parameters

• statusstringoptional

  open (default), pending, resolved, dismissed, or all.

• signal_typestringoptional

  no_knowledge, weak_match, negative_feedback or escalation.

• channel · since · limit · starting_afteroptional

  since filters on last_seen_at.

GET /media lists every item with its public URL. POST /media uploads one as multipart/form-data: the file in a field named file, plus name (required), description and category. PATCH /media/{id} changes name, description or category. DELETE /media/{id} removes the item and its file. Writes need the write scope.

• Limits

  JPEG, PNG, MP4 or MOV. 8 MB for images, 25 MB for videos. 20 items per library; the 21st is 403 plan_limit_reached.

• categorystring

  transformation, testimonial, before_after, product, pricing, general. The AI uses the category and description to pick the right item for a reply.

GET /blocked-users lists active blocks. POST /blocked-users blocks someone: send exactly one of ig_username (an Instagram handle, with or without the @, works before they have ever messaged you) or conversation_id (the person behind an existing conversation on Facebook or Instagram). DELETE /blocked-users/{id} unblocks; the AI answers their next message. Writes need the write scope.

Blocking someone already on the list is 409 already_blocked. The block row is kept after an unblock for audit, so ids are never reused.

A comment trigger watches comments on your posts, stories or Instagram Lives for keywords. When one matches it can post a public reply, send a DM with up to three buttons, hide the comment, tag the person, and start a flow. Standard CRUD: GET /comment-triggers (filters platform, source_type, active, post_id), POST, GET /comment-triggers/{id}, PATCH (partial), DELETE, plus POST /comment-triggers/{id}/duplicate (send {} as JSON; a bodiless POST is refused) and GET /comment-triggers/{id}/stats. Writes need the write scope.

Fields

• keywords · match_type · exclude_keywordsarray · string · array

  Any keyword matches. match_type is contains (default, anywhere in the text), exact (whole word) or fuzzy (tolerates a typo). An excluded word anywhere in the comment stops the trigger.

• platform · source_type · post_idstring · string · string

  platform is instagram, facebook or both. source_type is comment (posts and Reels), story (story replies), both, or live; story and live are Instagram only. A post_id from GET /recent-posts scopes the trigger to one post; null means every post.

• response_mode · public_replies · dm_templatesstring · array · array

  both, public_only or dm_only. Up to five variations each; one is picked per fire. Set dm_use_ai with a dm_ai_goal to have the AI write the DM from your knowledge base instead of templates.

• buttonsarray, 1 to 3

  Required for any DM mode: Meta needs a button on a comment-triggered DM. Each is {title, type, response | url}; titles are 20 characters max, text buttons send response when tapped, url buttons open url.

• activeboolean, PATCH only

  true activates, false pauses (and pauses linked flows). Plans cap how many triggers are live at once; creating past the cap saves the trigger paused with created_paused: true, and activating past it is 403 plan_limit_reached. Activating a trigger whose linked flow is paused, broken, or one of several is 409 flow_conflict.

• linked_flowsread-only

  Flows that start from this trigger, with entry immediate (starts when the trigger fires) or button (starts when the person taps a trigger button). A flow can also match comment keywords of its own with no trigger; that shows on GET /flows as a source with mode: native and is not a comment trigger.

The AI Comment Manager, which answers public comments with your knowledge base when no trigger fires, is a separate feature and is not a trigger.

A dry run. Pass text, platform and optionally post_id and source_type as query parameters, and get back what would happen: the trigger that fires and what it would send, the linked flow that would start, or the flow with native keywords that would answer if no trigger fires. Every trigger on the account is listed under candidates with the reason it did not fire (inactive, platform, source_type, post_scope, excluded_keyword, no_keyword_match, earlier_trigger_wins). It runs the same matcher as live traffic, sends nothing and records nothing. Read scope.

outcome is trigger_fired, native_flow, no_match, or automation_off when the account's Meta automation switch is off. Per-person rules (opt-out, blocked, once per user) are not simulated.

Recent posts and Reels already on the connected Instagram or Facebook account, newest first, fetched live from Meta (not Content Studio drafts; those are /posts). Use a post's id as post_id to scope a trigger to it. platform is instagram (default) or facebook; limit up to 50; starting_after takes the returned next_cursor. 409 not_connected when that channel is not connected, 503 service_unavailable when Meta does not answer.

The AI Comment Manager handles post and Reel comments that no comment trigger claimed. For each one it checks your exclusion rules, hides the comment if moderation flags it (spam, profanity, negativity, competitor links, self-promotion, whichever you turned on, with an optional DM to the person), writes a reply from your knowledge base, and either posts it (auto mode) or queues it for a person to approve (approval mode). This resource is that log and that queue. Settings are the comment_ai section of /ai/config. Pro plans and above; below that every route is 403 feature_unavailable.

GET /comments lists handled comments, newest first, kept 30 days. Filters: status, channel, post_id, since. status=pending is the approval queue. GET /comments/stats gives the queue depth and today's and this month's counts against the plan's caps.

The approval queue

• POST /comments/{id}/approvewrite

  Posts the pending reply publicly under the comment, as your account. Send {"text": "..."} to post your own wording instead of the AI draft; the draft is kept and reply.edited becomes true. Send {} to post the draft as is. Only a pending comment can be approved (409 not_pending). If Meta refuses the reply the row becomes failed and you get 422 send_failed.

• POST /comments/{id}/rejectwrite

  Drops the pending draft. Nothing is posted. Body {}.

• POST /comments/approve · /comments/rejectwrite, bulk

  Body {"ids": [...]}, up to 100. Approve returns approved, failed and one error line per failed id; reject returns how many changed. Ids that are not pending are skipped, never an error.

status

pending a draft is waiting for approval · sent the reply was posted · moderated the comment was hidden · rejected a person dropped the draft · failed Meta refused the reply, or the AI could not draft one · skipped the plan's daily or monthly cap was reached.

Every state change also fires the comment.handled webhook, so a queue can be worked from Slack or a help desk without polling.

Content Studio: draft, schedule and publish posts to Instagram, Facebook and TikTok, with the same publisher the portal uses. The flow is: read capabilities, create the post, upload its media, then publish now or schedule. Content Studio plans only; below that every route is 403 feature_unavailable. Writes need the write scope.

Fields

• platform · post_typestring · string

  platform is a target set: instagram, facebook, tiktok, both (Instagram and Facebook), instagram_tiktok, facebook_tiktok, all. The response expands it as targets. post_type is feed_post, carousel, reels or story. TikTok takes feed posts and Reels only.

• caption · hashtags · scheduled_at

  Caption up to 2,200 characters; hashtags without the #. scheduled_at is ISO-8601; set it on create or PATCH to schedule, send null on PATCH to go back to draft. Scheduling needs a caption (stories excepted) and a future time.

• advancedfirst_comment · collaborators · comment_auto_reply

  Sent as top-level fields, returned under advanced. first_comment is posted under the post right after publish. collaborators are up to three Instagram usernames invited to co-own the post. comment_auto_reply {keywords, match_type, response_mode, public_replies, dm_templates, buttons} becomes a comment trigger scoped to this post when it publishes; any DM mode needs at least two buttons. None of the three apply to a TikTok-only post.

• tiktokobject

  The TikTok Settings block: privacy_level (must be one of the creator's options from capabilities), title (up to 150, defaults to the caption), allow_comments, allow_duet, allow_stitch, and the content disclosure: content_disclosure with promote_self and/or promote_third_party. Ignored unless TikTok is a target; null in the response otherwise.

• statusread-only

  draft · scheduled (the scheduler publishes it within a minute of scheduled_at) · publishing · published (see published_ids) · failed (see error_message, then retry). Only draft, scheduled and failed posts can be edited; published posts cannot be deleted.

Read this before building a post. It says which of Instagram, Facebook and TikTok are connected, the TikTok creator's allowed privacy_level_options and video duration limit (fetched live from TikTok, the full list when TikTok is not connected or does not answer), the post types, and the plan's monthly post cap and storage cap with what is used.

POST /posts/{id}/media uploads one file as multipart/form-data in a field named file, with an optional sort_order. Call it once per item. JPEG, PNG or WebP up to 8 MB and 320 to 1440 px wide; MP4 or MOV up to 1 GB, 3 seconds to 15 minutes for Reels and up to 60 seconds for stories. A carousel takes 2 to 10 items. Uploads count against the plan's storage cap (403 plan_limit_reached). Every media call returns the post.

PATCH /posts/{id}/media with {"order": [mediaId, ...]} reorders; list every id. DELETE /posts/{id}/media/{mediaId} removes the file.

• POST /posts/{id}/publishbody {}

  Publishes to every target at once. Needs a caption (stories excepted), media for any Instagram target, and two or more items for a carousel. When a platform rejects it the post becomes failed and the call is 422 publish_failed with the post and per-platform results. post.published or post.failed fires either way.

• POST /posts/{id}/schedule{"scheduled_at"}

  Sets or moves the publish time of a draft, failed or scheduled post. The scheduler publishes it within a minute of that time and fires the same events. post.scheduled fires now.

• POST /posts/{id}/unschedulebody {}

  Scheduled back to draft.

• POST /posts/{id}/retrybody {}

  Publishes a failed post again, up to the retry cap.

Any of these on a post in the wrong status is 409 not_editable.

Every account you track, with the numbers from its latest stored snapshot, plus how many slots your plan allows. The whole set comes back in one page: has_more is always false.

last_snapshot_date is null until the first refresh, and status is error when Meta last refused the lookup, which usually means the account went private or changed handle.

Beyond the usual envelope

• trackedinteger

  Slots in use.

• max_trackedinteger

  Your plan's cap.

• remaininginteger

  What is left.

POST /competitors

Body is {"username": "nasa"}, with or without the leading @. The handle must be a public Instagram business or creator account: personal and private accounts are invisible to the API for everyone, and come back 422 invalid_param. At your plan's cap this is 403 plan_limit_reached, and an account you already track is 409 conflict. The first snapshot is taken immediately, so the response already carries follower and engagement numbers.

DELETE /competitors/{id}

Frees the slot. Snapshot history is kept, so re-adding the same handle later picks up where it left off rather than starting from zero.

Your account and every competitor ranked together, which is the one call to make for any "how do I compare" question. Each row carries followers, following, posts, engagement rate, average likes and comments, posts per week, follower growth per day and the content mix as percentages of reels, photos and carousels. Your own row has is_own_account: true, and your_rank saves you finding it.

Query parameters

• periodintegeroptional

  7, 30 (default) or 90. Anything else is a 400.

GET /market-intel/history

Follower count and engagement rate over the window, one series per account, oldest point first, yours first in the list. The account label is the competitor's handle, or the literal you for your own. One point per day a snapshot exists, so gaps mean nobody refreshed that day. Same period parameter.

GET /market-intel/wins

The comparisons already computed against each competitor over the last 30 days, split into wins where you lead and opportunities where they do. Each carries a metric (engagement, growth, posting), the competitor it is measured against, and a message written for a person with the gap in it. No AI is involved; this is arithmetic on the snapshots.

One competitor and your own account side by side, as the portal's comparison table. metrics[] holds a row per measure with you, them, the difference and you_lead. That last one is null for a metric with no better side, such as Following, so do not read a null as a loss. your_wins and competitor_wins count the decided rows.

Stored snapshots, no Meta call. A competitor id from another account is a 404, like everywhere else in this API.

The latest stored breakdown of your own followers. gender_percent and age_percent are shares, not counts, because that is all Instagram reports. top_countries and top_cities are lists of {country|city, count, percentage}, biggest first. online_followers_by_hour is what "when should I post" is answered from, and Instagram often omits it.

404 until the first refresh. Instagram withholds all of this for accounts under roughly 100 followers, which arrives as zeros and empty lists rather than an error.

GET /market-intel/top-posts

Your own recent posts with their stored performance: reach, impressions, likes, comments, saves, shares, video views, engagement rate and save rate, newest first. limit is 1 to 50, default 12. Stored, so refresh first if you need today's numbers.

GET /market-intel/insights

Reach, profile views, accounts engaged, interactions, saves, shares and follows for your own account. days is 1, 7 (default) or 30. This one calls Instagram live, so it takes a moment and counts against Meta's rate limit. Which metrics come back depends on what the account is eligible for, so read the object rather than assuming a fixed set. A connection made without the insights permission is 403 permission_required; reconnect in the portal to fix it.

Pulls current numbers from Meta for your account and every tracked competitor, then writes today's snapshot. Exactly what the portal's Refresh button does, and the source of everything the other routes read.

One Meta call per account, so it takes several seconds on a full slate. Five minutes are enforced between refreshes: too soon and you get 429 too_soon with retry_after_seconds telling you exactly how long to wait. Send {} as the body.

refreshed counts the competitors updated, errors[] names the ones Meta refused, usually because the account went private.