API reference
Everything in your portal, from your own code, in the same order: your account and its billing by module, connectors and knowledge bases shared by your agents, then each Customer Agent with its conversations, workflows and settings. Plus webhooks. Free with every package.
https://ai-api.marvoxa.com/v1JSON over HTTPSBearer key authSigned webhooksOn this page
Introduction
Marvoxa AI is a business suite: AI that knows your business and does the work. The API lets your own apps, CRM or backend use every module the way your console does: your account and team, knowledge, connectors, and Customer Agents (talk to an agent, read and answer conversations, change its settings and workflows). Webhooks tell your systems when something happens in a module.
A key reaches the modules you pick for it, and changes made through the API follow the same rules as the console and show there at once.
https://ai-api.marvoxa.com/v1Quickstart
1. In your console, open API and webhooks (under Developer) and create a secret key. Copy it: it's shown once.
2. Copy your agent's ID from the same page (or from its address in the portal).
3. Send your first message. The reply comes back in the same request.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/messages \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Hi! Do you ship to Chicago?",
"user": "customer-42"
}'How it's organised
The API follows your portal. Your key belongs to one account, so the account needs no ID in the address. The account comes first: its settings, team, webhooks, and Billing & usage (one total per module). Then what the account shares with every agent: connectors (apps and your own systems, connected once) and knowledge bases. Then Customer Agents: each agent's pages live under /agents/{agent_id}, named like the agent's menu in the portal (Conversations, Leads, Teach and Reach), and that's where knowledge bases and connectors are attached to it.
Answers are JSON. A single thing has an object field (agent, knowledge_base, connection, conversation...). Reads use GET, changes to settings use PATCH (send only what changes), new items use POST, and removing one uses DELETE.
/account the account
/settings /team /webhooks
/billing Billing & usage: by module, platform fee,
next payment; /invoices /transactions
/usage a month's usage by module
/connectors apps and own systems on the account (free)
/apps /{connection_id} /{connection_id}/check
/custom your own API or MCP server, and its tools
/{custom_id} /check /tools /tools/{tool_id}/test /activity
/import an API description, read into tools
/knowledge-bases knowledge bases
/{kb_id}/documents /search /tests /check
/knowledge-gaps questions no knowledge base answered
/agents Customer Agents
/{agent_id} the agent (its Agent settings page)
/messages talk to it as a customer
/conversations /leads
/knowledge-bases Teach: attached knowledge bases,
/connectors attached connectors (free),
/workflows /test workflows, testing
/artifacts
/channels Reach: channels, chat and voice
/chat-settings /voice-settings
/usage replies, voice minutes, extras, cost
/key /usage /voices your key, this month's replies, voicesAuthentication and access
Every request carries a secret key in the Authorization header as a bearer token. Keys start with mvx_sk_. Owners and admins create and revoke keys in the portal's Developers page.
Each key has an access level and reaches the modules picked when it's made: Customer Agents (/agents/...), Knowledge (/knowledge-bases, /knowledge-gaps), Connectors (/connectors) and Account (/account/...). A key for all modules also reaches modules that launch later. Inside Customer Agents, a key reaches every agent or only the agents you tick. Listing what an agent uses needs only Customer Agents; attaching a knowledge base or connection to it needs Knowledge or Connectors too. /key, /usage and /voices work with any key. Each endpoint below says what it needs.
Keep keys on your server. Never put a key in a website's code, a mobile app or a public repository: anyone with it can use your account at its level. If a key leaks, revoke it in the portal and it stops working at once. Requests from other websites' browsers are blocked.
readRead everything the key reaches: agents, settings, knowledge, conversations, usage, billing.
messagesAlso talk to agents as a customer, and send test messages. Keys made before access levels existed have this.
fullAlso change things: agents and their settings, knowledge bases, connectors, artifacts, channels, workflows, conversations (take over and reply), team members, account settings and webhooks.
Authorization: Bearer mvx_sk_...Billing and limits
The API is free with every package, including the free trial. Each reply your agent sends through the API counts as one customer reply in your package, exactly like a reply on your website or WhatsApp. Reading and changing things costs nothing.
When this month's replies are used, replies continue as extra replies at your package's price per reply if extras are on for your account (within your monthly limit, if you have one). Otherwise messages are saved for your team and come back with status held, without an AI reply or a charge. Every reply shows how it was paid in usage.charge.
A message can be up to 2,000 characters. Each key can send 60 messages, make 60 changes and 300 requests in all a minute; more returns 429. Packages, payments and API keys are managed in the portal, not through the API.
trialFrom your free trial.
includedFrom this month's package.
extraBeyond the package, charged at its price per reply (usage.price_usd).
Conversations
A message without conversation_id starts a new conversation and returns its ID. Send that ID with the next message to carry on: the agent remembers what was said, like a chat on your website.
Pass user with your own ID for the person (a customer number, an email). It's shown in your portal's Conversations and on webhooks, and you can list a person's conversations with it.
If a customer asks for a person and human help is on, the reply has handoff: true and the conversation appears in your portal's Inbox. While someone from your team has it, messages return status with_person: they're saved for your team and the AI stays quiet. With a full-access key, your own system can take a conversation over, reply as your team and hand it back.
Lists and pages
A list is {"object": "list", "data": [...], "has_more": false}, sometimes with a few fields about the whole list beside data (a word limit, a price). Most lists come whole. The long ones (conversations, messages and leads) come a page at a time: ask for up to 100 with limit, and when has_more is true, ask for the next page with before.
For conversations and leads, before is the last item's last_message_at or created_at. For messages, it's the ID of the first message on the page you have (messages come oldest first, so pages go back in time).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations?limit=20&before=2026-11-01T10:00:02%2B00:00 \
-H "Authorization: Bearer $MARVOXA_API_KEY"Errors
Errors use normal HTTP status codes and a JSON body with a type and a readable message.
401typeauthentication_error
WhenNo key, or a wrong or revoked one.
403typepermission_denied
WhenThe account is paused, the key's access level doesn't allow it, or the key doesn't reach this module.
404typenot_found
WhenThe agent, conversation or item isn't one this key can reach.
409typeconflict
WhenNot possible right now: the agent is still being set up or switched off, a limit is reached, or your package doesn't include it.
422typeinvalid_request
WhenA field is missing, too long or not one of the choices.
429typerate_limit_exceeded
WhenToo many requests; wait a little and try again.
502typeagent_error
WhenThe AI couldn't answer this time; try again.
{
"error": {
"type": "authentication_error",
"message": "That API key isn't valid, or was revoked."
}
}Account
Your account
In the portal: Your account
The account your key belongs to. Everything else hangs from it: its settings, team, webhooks, Billing & usage, connectors, knowledge bases and agents.
Get the account
/accountYour business, its status and how many agents it has.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/account \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"object": "account",
"name": "Lumora Studio",
"status": "active",
"industry": "fashion",
"website": "https://lumora.studio",
"agents": 2
}Your key
In the portal: Developers › API keys
The key making the request, and this month's replies. Any key can read these, including one limited to some agents.
Get your key
/keyIts name, access level, the modules it reaches (modules is empty and all_modules true when it reaches all of them) and, in Customer Agents, the agents (agent_ids is empty for all of them).
Any key
curl https://ai-api.marvoxa.com/v1/key \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "api_key",
"name": "Website backend",
"key": "mvx_sk_7Qd…a1b2",
"account": "Lumora Studio",
"access": "messages",
"modules": [],
"all_modules": true,
"agent_ids": [],
"agents": [],
"agent_id": null
}Get this month's replies
/usageYour package's replies this period, how many are used, and how many went through the API (only the key's agents', for a key limited to some). For a full breakdown, see Billing.
Any key
curl https://ai-api.marvoxa.com/v1/usage \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "usage",
"period_start": "2026-11-01T00:00:00+05:00",
"period_end": "2026-12-01T00:00:00+05:00",
"plan": {
"status": "active",
"included_replies": 3000,
"used_replies": 1312,
"extra_replies_allowed": true
},
"api": {
"replies": 418,
"extra_spend_usd": "0.000000"
},
"owed_usd": "0"
}Settings
In the portal: Settings
Your business details, as on the portal's Settings page. Needs a key that reaches this module.
Get settings
/account /settingsYour business name, owner and industry.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/account/settings \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "account_settings",
"business_name": "Lumora Studio",
"owner_name": "Sam Rivera",
"owner_phone": "(718) 555-0136",
"industry": "fashion"
}Update settings
/account /settingsSend only what changes.
Full accessKey that reaches this module
Body
business_namestringUp to 160 characters.
owner_namestringUp to 120 characters.
owner_phonestringDigits, spaces,
+,-and brackets.industrystringUp to 40 characters.
curl -X PATCH https://ai-api.marvoxa.com/v1/account/settings \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"owner_phone": "(718) 555-0199"
}'{
"object": "account_settings",
"business_name": "Lumora Studio",
"owner_name": "Sam Rivera",
"owner_phone": "(718) 555-0199",
"industry": "fashion"
}Team members
In the portal: Team
The people who use your portal. Through the API you can add members, pause them and remove them. The owner and admins are managed in the portal. Needs a key that reaches this module.
List team members
/account /teamEveryone on your team. role is owner, admin or member; invited means they haven't signed in yet.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/account/team \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "6f8a0c2e-4b6d-4f8a-9c2e-4b6d8f0a2c4e",
"object": "team_member",
"name": "Nora Park",
"email": "nora@lumora.studio",
"role": "member",
"active": true,
"invited": true,
"last_login_at": null,
"created_at": "2026-11-01T10:00:00+00:00"
}
],
"has_more": false
}Add a team member
/account /teamAdds a member and emails them a temporary password. If the email couldn't be sent (emailed: false), the password is in this answer, once, to pass on yourself.
Full accessKey that reaches this module
Body
namestringrequiredUp to 120 characters.
emailstringrequiredTheir email; they sign in with it.
curl -X POST https://ai-api.marvoxa.com/v1/account/team \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Nora Park",
"email": "nora@lumora.studio"
}'{
"id": "6f8a0c2e-4b6d-4f8a-9c2e-4b6d8f0a2c4e",
"object": "team_member",
"name": "Nora Park",
"email": "nora@lumora.studio",
"role": "member",
"active": true,
"invited": true,
"last_login_at": null,
"created_at": "2026-11-01T10:00:00+00:00",
"emailed": true
}Pause or restore a member
/account /team /{user_id}active: false stops them signing in until restored.
Full accessKey that reaches this module
Path parameters
user_idstringrequiredThe team member's ID.
Body
activebooleanCan sign in (true) or paused (false).
curl -X PATCH https://ai-api.marvoxa.com/v1/account/team/$USER_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"active": false
}'{
"id": "6f8a0c2e-4b6d-4f8a-9c2e-4b6d8f0a2c4e",
"object": "team_member",
"name": "Nora Park",
"email": "nora@lumora.studio",
"role": "member",
"active": false,
"invited": true,
"last_login_at": null,
"created_at": "2026-11-01T10:00:00+00:00"
}Remove a member
/account /team /{user_id}They can't sign in any more.
Full accessKey that reaches this module
Path parameters
user_idstringrequiredThe team member's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/account/team/$USER_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "6f8a0c2e-4b6d-4f8a-9c2e-4b6d8f0a2c4e",
"object": "team_member",
"deleted": true
}Billing & usage
Billing & usage
In the portal: Billing & usage
The whole account at a glance, as in the portal: one total per module (Customer Agents, Ask Marvoxa and Ask agent, Knowledge), the platform fee as a line of the account's own, what renews next, and every charge and payment. Each module's details live in the module (an agent's usage: Customer Agents › Usage). Package changes and payments are made in the portal. Needs a key that reaches this module.
Get billing & usage
/account /billingThis month by module (modules), each with its total_usd and parts; Customer Agents also lists its subscriptions, your packages (chat replies and voice minutes). platform_fee is null without a paying package. next_payment is the next renewal: amount_usd is what it takes after your balance, by_module what renews, before it. plans and the fields after it are what this answer has always had. locked is trial_over or no_plan when every channel is off.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/account/billing \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "billing",
"plans": {
"chat": {
"status": "active",
"live": true,
"tier": "standard",
"tier_name": "Standard",
"package": "starter",
"package_name": "Starter",
"allowance": 3000,
"used": 1312,
"price_usd": "9.00",
"period_start": "2026-11-01T00:00:00+05:00",
"period_end": "2026-12-01T00:00:00+05:00",
"auto_renew": true,
"extra_price_usd": "0.004"
},
"voice": null
},
"trial_available": {
"chat": false,
"voice": true
},
"trial_days": 7,
"locked": null,
"extra_usage": true,
"monthly_cap_usd": "100.00",
"balance_usd": "-6.050000",
"due_usd": "0.000000",
"month": "2026-11",
"modules": [
{
"object": "billing_module",
"key": "customer_agents",
"name": "Customer Agents",
"status": "live",
"total_usd": "10.20",
"free": false,
"parts": {
"subscriptions_usd": "9.00",
"channels_and_apps_usd": "0.00",
"extras_usd": "1.20"
},
"subscriptions": [
{
"object": "subscription",
"id": "d4f6a8c0-2e4b-4d6f-8a0c-2e4b6d8f0a2c",
"module": "customer_agents",
"kind": "chat",
"status": "active",
"live": true,
"tier": "standard",
"tier_name": "Standard",
"package": "starter",
"package_name": "Starter",
"bundle": null,
"bundle_name": null,
"allowance": 3000,
"used": 1312,
"price_usd": "9.00",
"renewal_usd": "9.00",
"period_start": "2026-11-01T00:00:00+05:00",
"period_end": "2026-12-01T00:00:00+05:00",
"auto_renew": true
}
]
},
{
"object": "billing_module",
"key": "ask",
"name": "Ask Marvoxa and Ask agent",
"status": "live",
"total_usd": "0.85",
"free": false,
"parts": {
"extras_usd": "0.85"
},
"subscriptions": []
},
{
"object": "billing_module",
"key": "knowledge",
"name": "Knowledge",
"status": "included",
"total_usd": null,
"free": false,
"parts": {},
"subscriptions": []
}
],
"platform_fee": {
"object": "platform_fee",
"name": "Platform fee",
"amount_usd": "4.00",
"monthly_usd": "4.00",
"free": false,
"note": "Monthly, for the whole account. Part of the chat subscription's price."
},
"month_total_usd": "15.05",
"subscriptions": [
{
"object": "subscription",
"id": "d4f6a8c0-2e4b-4d6f-8a0c-2e4b6d8f0a2c",
"module": "customer_agents",
"kind": "chat",
"status": "active",
"live": true,
"tier": "standard",
"tier_name": "Standard",
"package": "starter",
"package_name": "Starter",
"bundle": null,
"bundle_name": null,
"allowance": 3000,
"used": 1312,
"price_usd": "9.00",
"renewal_usd": "9.00",
"period_start": "2026-11-01T00:00:00+05:00",
"period_end": "2026-12-01T00:00:00+05:00",
"auto_renew": true
}
],
"next_payment": {
"on": "2026-12-01T00:00:00+05:00",
"amount_usd": "19.05",
"by_module": [
{
"module": "platform_fee",
"amount_usd": "4.00"
},
{
"module": "customer_agents",
"amount_usd": "9.00"
}
]
},
"owed_usd": "6.05",
"credit_usd": "0.00"
}Get usage by module
/account /usageA month's usage, module by module: Customer Agents' replies, voice minutes and spend (spend_usd is replies and voice calls together, split in replies_spend_usd and voice_spend_usd; by_agent and by_channel share out reply spend), your team's questions to Ask Marvoxa and Ask agent, and your knowledge bases. extras lists every extra line by line, with the module it belongs to; value_usd is what it's worth at our prices when it was free on your package.
Any keyKey that reaches this module
Query parameters
monthstringYYYY-MM(month01to12). This month if left out.
curl https://ai-api.marvoxa.com/v1/account/usage \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "account_usage",
"month": "2026-11",
"modules": [
{
"object": "module_usage",
"key": "customer_agents",
"name": "Customer Agents",
"replies": 1312,
"extra_replies": 96,
"conversations": 284,
"voice_minutes": 88.5,
"calls": {
"count": 41,
"seconds": 5310,
"charge_usd": "0.000000",
"avg_response_ms": 820
},
"spend_usd": "1.200000",
"replies_spend_usd": "1.200000",
"voice_spend_usd": "0.000000",
"by_agent": [
{
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava",
"replies": 1312,
"spend_usd": "1.200000"
}
],
"by_channel": [
{
"channel": "web",
"replies": 702,
"spend_usd": "0.640000"
},
{
"channel": "whatsapp",
"replies": 492,
"spend_usd": "0.450000"
},
{
"channel": "api",
"replies": 118,
"spend_usd": "0.110000"
}
]
},
{
"object": "module_usage",
"key": "ask",
"name": "Ask Marvoxa and Ask agent",
"answers": 64,
"spend_usd": "0.850000"
},
{
"object": "module_usage",
"key": "knowledge",
"name": "Knowledge",
"knowledge_bases": 3,
"documents": 18,
"words": 9420
}
],
"extras": [
{
"key": "customer_replies",
"label": "Extra customer chat replies",
"detail": "96 replies",
"amount_usd": "1.200000",
"value_usd": "1.200000",
"module": "customer_agents"
},
{
"key": "ai",
"label": "Ask agent · AI answers",
"detail": "64 answers",
"amount_usd": "0.850000",
"value_usd": "0.850000",
"module": "ask"
}
],
"spend_usd": "2.050000"
}List invoices
/account /billing /invoicesYour invoices, newest first. Totals are in US cents and paisa.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/account/billing/invoices \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "1e3a5c7e-9b1d-4e3a-8c5e-7a9c1e3b5d7f",
"object": "invoice",
"number": "MVX-2026-0142",
"month": "2026-10",
"issued_on": "2026-11-01",
"status": "issued",
"total_usd_cents": 4900,
"total_pkr_paisa": 1372000
}
],
"has_more": false
}Get an invoice
/account /billing /invoices /{invoice_id}One invoice with its lines and exchange rate.
Any keyKey that reaches this module
Path parameters
invoice_idstringrequiredThe invoice's ID.
curl https://ai-api.marvoxa.com/v1/account/billing/invoices/$INVOICE_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "1e3a5c7e-9b1d-4e3a-8c5e-7a9c1e3b5d7f",
"object": "invoice",
"number": "MVX-2026-0142",
"month": "2026-10",
"issued_on": "2026-11-01",
"status": "issued",
"total_usd_cents": 900,
"total_pkr_paisa": 252000,
"usd_to_pkr": "280.00",
"lines": [
{
"kind": "plan",
"description": "Standard: Starter",
"detail": "1 Nov to 30 Nov",
"usd_cents": 900,
"pkr_paisa": 252000
}
]
}List transactions
/account /billing /transactionsA month's charges and payments, newest first, with extra replies grouped by day. kind is topup, plan, plan_credit, usage, voice, addon, refund or adjustment.
Any keyKey that reaches this module
Query parameters
monthstringYYYY-MM(month01to12). This month if left out.
curl https://ai-api.marvoxa.com/v1/account/billing/transactions \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"object": "transaction",
"at": "2026-11-01T10:00:00+00:00",
"kind": "plan",
"amount_usd": "-9.00",
"note": "Standard: Starter"
}
],
"has_more": false,
"month": "2026-11"
}Connectors
Connectors
In the portal: Connectors
Apps your agents work with, such as Google Sheets, Calendar or your CRM, connected once to your account. Ask Marvoxa can use them, and you attach a connection to each agent that should use it (Customer Agents › Connectors). Connecting needs the app's own sign-in, so you get a link to send the person to, then check the connection when they're back. Your own systems are connections too (see Custom connectors). Needs a key that reaches this module.
List connections
/connectorsThe apps and own systems connected to your account, oldest first, and the agents each is attached to (agents, with that agent's connector_id). kind is app, or api or mcp for your own system: those have no app, and add their address and how many tools agents may use. status is connecting (waiting for the sign-in), live or failed.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/connectors \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e",
"object": "connection",
"kind": "app",
"app": "googlesheets",
"name": "Google Sheets",
"logo": "https://logos.composio.dev/api/googlesheets",
"label": "Google Sheets",
"status": "live",
"private": false,
"created_at": "2026-10-20T08:15:00+00:00",
"agents": [
{
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava",
"connector_id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"enabled": true,
"billing": "free",
"status": "live"
}
]
},
{
"id": "b2d4f6a8-0c1e-4b3d-9f5a-7c9e1b3d5f7a",
"object": "connection",
"kind": "api",
"app": null,
"name": "Orders",
"logo": null,
"label": "Orders",
"status": "live",
"private": false,
"created_at": "2026-10-28T12:00:00+00:00",
"agents": [
{
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava",
"connector_id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"enabled": true,
"billing": "paid",
"status": "live"
}
],
"address": "https://api.lumora.studio/v1",
"tools": 2,
"needs_sign_in": false
}
],
"has_more": false,
"ready": true,
"price_per_agent_monthly_usd": "0.00",
"grace_hours": 24
}List apps
/connectors /appsThe apps you can connect, featured first. private: true means the app holds conversations of its own (an inbox, say) that your agents could read: connecting it needs understood: true.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/connectors/apps \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"object": "app",
"slug": "googlesheets",
"name": "Google Sheets",
"logo": "https://logos.composio.dev/api/googlesheets",
"description": "Read and write rows in your spreadsheets.",
"categories": [
"Productivity"
],
"featured": true,
"private": false
}
],
"has_more": false,
"ready": true,
"categories": [
"CRM",
"Productivity"
],
"price_per_agent_monthly_usd": "0.00",
"grace_hours": 24
}Connect an app
/connectorsStarts connecting an app to your account, for free. Send the person to redirect_url to sign in to the app; they come back to your portal's Connectors page. Then check the connection: it's live once they've signed in. With agent_id, it's attached to that agent as soon as it's live (and that agent's month is charged then).
Full accessKey that reaches this module
Body
appstringrequiredThe app's
slug, from List apps.understoodbooleanYou accept that a
privateapp lets your agents read its conversations. Needed for those apps.agent_idstringAttach it to this agent once it's live.
curl -X POST https://ai-api.marvoxa.com/v1/connectors \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"app": "googlesheets"
}'{
"object": "connection_link",
"redirect_url": "https://connect.composio.dev/link/ln_7c2e9a",
"expires_at": "2026-11-01T10:10:00Z",
"connection": {
"id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e",
"object": "connection",
"kind": "app",
"app": "googlesheets",
"name": "Google Sheets",
"logo": "https://logos.composio.dev/api/googlesheets",
"label": "Google Sheets",
"status": "connecting",
"private": false,
"created_at": "2026-10-20T08:15:00+00:00",
"agents": []
}
}Get a connection
/connectors /{connection_id}One connected app, and the agents it's attached to.
Any keyKey that reaches this module
Path parameters
connection_idstringrequiredThe connection's ID.
curl https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e",
"object": "connection",
"kind": "app",
"app": "googlesheets",
"name": "Google Sheets",
"logo": "https://logos.composio.dev/api/googlesheets",
"label": "Google Sheets",
"status": "live",
"private": false,
"created_at": "2026-10-20T08:15:00+00:00",
"agents": [
{
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava",
"connector_id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"enabled": true,
"billing": "free",
"status": "live"
}
]
}Check the sign-in
/connectors /{connection_id} /checkAsks the app whether the sign-in finished. The connection is live once it has, or failed if it was refused or given up.
Full accessKey that reaches this module
Path parameters
connection_idstringrequiredThe connection's ID.
curl -X POST https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID/check \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e",
"object": "connection",
"kind": "app",
"app": "googlesheets",
"name": "Google Sheets",
"logo": "https://logos.composio.dev/api/googlesheets",
"label": "Google Sheets",
"status": "live",
"private": false,
"created_at": "2026-10-20T08:15:00+00:00",
"agents": [
{
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava",
"connector_id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"enabled": true,
"billing": "free",
"status": "live"
}
]
}Remove an app
/connectors /{connection_id}Removes the app from your account. It's detached from every agent first; each agent detached within grace_hours of being charged gets its month back (refunded_usd, the total).
Full accessKey that reaches this module
Path parameters
connection_idstringrequiredThe connection's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e",
"object": "connection",
"deleted": true,
"refunded_usd": "0.000000"
}Custom connectors
In the portal: Connectors › Add a connector › Custom connector
Your own systems, connected like apps so agents can look up and change your live data while they talk. An API connector holds the tools you make for it (one thing an agent can do, like looking up an order); an MCP server lists its own tools, and you choose which ones agents may use. Each is a connection on your account (in List connections, with kind api or mcp), attached to agents like an app (Customer Agents › Connectors) at the same price. Keys, tokens and passwords are sent once and stored encrypted: answers only say which are saved (secrets_set). A tool that changes something (changes: true) asks the customer to confirm before it runs. Needs a key that reaches this module.
Connect your own system
/connectors /customSaves your API or MCP server on your account, for free, and tests it (check). An API is saved even if the test fails, so you can fix it later; then add its tools. An MCP server is connected and its tools listed: they're all on except those the server marks as destructive. A tool is marked changes when the server says it changes things. When the server doesn't say, it's marked changes when its name says it creates, sends, updates, deletes or books something, or doesn't say clearly that it only reads. A server that signs in on its own page (OAuth) is connected from the console instead (422).
Full accessKey that reaches this module
Body
kindstringrequiredapiormcp.namestringrequiredWhat you and your agents call it (1 to 120 characters).
base_urlstringAn API's address, like
https://api.yourcompany.com/v1. Needshttps.urlstringAn MCP server's address, like
https://mcp.yourcompany.com/mcp. Needshttps.authobjectrequiredHow it signs in:
{type}, withtypeone ofnone,api_key(addin:headerorquery, andname, likeX-API-Key),bearer,basicoroauth_client(addtoken_urland an optionalscope) for an API;none,bearerorheader(addname) for an MCP server.secretsobjectThe keys it needs, each a string:
api_key,token,usernameandpassword,client_idandclient_secret, orheader(the custom header's value).headersarrayAn API's extra headers, sent with every call (up to 10):
[{name, value}]. Their values are kept like keys.
curl -X POST https://ai-api.marvoxa.com/v1/connectors/custom \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "api",
"name": "Orders",
"base_url": "https://api.lumora.studio/v1",
"auth": {
"type": "api_key",
"in": "header",
"name": "X-API-Key"
},
"secrets": {
"api_key": "sk_live_…"
}
}'{
"id": "b2d4f6a8-0c1e-4b3d-9f5a-7c9e1b3d5f7a",
"object": "custom_connector",
"kind": "api",
"name": "Orders",
"status": "live",
"needs_sign_in": false,
"address": "https://api.lumora.studio/v1",
"auth": {
"type": "api_key",
"in": "header",
"name": "X-API-Key"
},
"secrets_set": [
"api_key"
],
"headers": [],
"timeout_s": 8,
"calls_per_minute": 60,
"server": null,
"transport": null,
"check": {
"ok": true,
"status": 200,
"ms": 212,
"message": "Connected. The API answered in 212 ms.",
"at": "2026-11-01T10:00:00+00:00"
},
"tools_refreshed_at": null,
"tools": [],
"agents": [],
"stats": {
"calls_7d": 1284,
"ok_7d": 1274,
"failed_7d": 10,
"avg_ms_7d": 310
},
"created_at": "2026-10-28T12:00:00+00:00",
"created_by": "Sam Rivera"
}List custom connectors
/connectors /customYour own systems, oldest first, each as Get a custom connector shows it: its connection (never its keys), tools, agents and last 7 days. They're in List connections too, more briefly.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/connectors/custom \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "b2d4f6a8-0c1e-4b3d-9f5a-7c9e1b3d5f7a",
"object": "custom_connector",
"kind": "api",
"name": "Orders",
"status": "live",
"needs_sign_in": false,
"address": "https://api.lumora.studio/v1",
"auth": {
"type": "api_key",
"in": "header",
"name": "X-API-Key"
},
"secrets_set": [
"api_key"
],
"headers": [],
"timeout_s": 8,
"calls_per_minute": 60,
"server": null,
"transport": null,
"check": {
"ok": true,
"status": 200,
"ms": 212,
"message": "Connected. The API answered in 212 ms.",
"at": "2026-11-01T10:00:00+00:00"
},
"tools_refreshed_at": null,
"tools": [
{
"id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
"object": "connector_tool",
"key": "get_order",
"name": "Look up an order",
"description": "When a customer asks where their order is, what's in it or when it arrives.",
"source": "openapi",
"enabled": true,
"changes": false,
"position": 0,
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
],
"fixed": [],
"fields": [
"id",
"status",
"items.name",
"delivery.expected"
],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": "2026-11-01T10:00:00+00:00",
"test_ok": true
},
{
"id": "a0c2e4b6-8d0f-4a2c-b4e6-8f0a2c4e6b8d",
"object": "connector_tool",
"key": "cancel_order",
"name": "Cancel an order",
"description": "When a customer asks to cancel an order that hasn't been sent yet.",
"source": "openapi",
"enabled": true,
"changes": true,
"position": 1,
"method": "POST",
"path": "/orders/{order_id}/cancel",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
},
{
"name": "reason",
"in": "body",
"type": "string",
"required": false,
"description": "Why the customer is cancelling, in their words.",
"enum": null,
"example": null
}
],
"fixed": [],
"fields": [],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": null,
"test_ok": null
}
],
"agents": [
{
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava",
"connector_id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"enabled": true,
"billing": "paid",
"status": "live"
}
],
"stats": {
"calls_7d": 1284,
"ok_7d": 1274,
"failed_7d": 10,
"avg_ms_7d": 310
},
"created_at": "2026-10-28T12:00:00+00:00",
"created_by": "Sam Rivera"
}
],
"has_more": false,
"price_per_agent_monthly_usd": "0.00",
"grace_hours": 24
}Get a custom connector
/connectors /custom /{custom_id}One own system: its connection (never its keys), its tools, the agents it's attached to, and its last 7 days (stats). needs_sign_in is true when an MCP server's own sign-in ran out: sign in again from the console.
Any keyKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).
curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "b2d4f6a8-0c1e-4b3d-9f5a-7c9e1b3d5f7a",
"object": "custom_connector",
"kind": "api",
"name": "Orders",
"status": "live",
"needs_sign_in": false,
"address": "https://api.lumora.studio/v1",
"auth": {
"type": "api_key",
"in": "header",
"name": "X-API-Key"
},
"secrets_set": [
"api_key"
],
"headers": [],
"timeout_s": 8,
"calls_per_minute": 60,
"server": null,
"transport": null,
"check": {
"ok": true,
"status": 200,
"ms": 212,
"message": "Connected. The API answered in 212 ms.",
"at": "2026-11-01T10:00:00+00:00"
},
"tools_refreshed_at": null,
"tools": [
{
"id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
"object": "connector_tool",
"key": "get_order",
"name": "Look up an order",
"description": "When a customer asks where their order is, what's in it or when it arrives.",
"source": "openapi",
"enabled": true,
"changes": false,
"position": 0,
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
],
"fixed": [],
"fields": [
"id",
"status",
"items.name",
"delivery.expected"
],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": "2026-11-01T10:00:00+00:00",
"test_ok": true
},
{
"id": "a0c2e4b6-8d0f-4a2c-b4e6-8f0a2c4e6b8d",
"object": "connector_tool",
"key": "cancel_order",
"name": "Cancel an order",
"description": "When a customer asks to cancel an order that hasn't been sent yet.",
"source": "openapi",
"enabled": true,
"changes": true,
"position": 1,
"method": "POST",
"path": "/orders/{order_id}/cancel",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
},
{
"name": "reason",
"in": "body",
"type": "string",
"required": false,
"description": "Why the customer is cancelling, in their words.",
"enum": null,
"example": null
}
],
"fixed": [],
"fields": [],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": null,
"test_ok": null
}
],
"agents": [
{
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava",
"connector_id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"enabled": true,
"billing": "paid",
"status": "live"
}
],
"stats": {
"calls_7d": 1284,
"ok_7d": 1274,
"failed_7d": 10,
"avg_ms_7d": 310
},
"created_at": "2026-10-28T12:00:00+00:00",
"created_by": "Sam Rivera"
}Update a custom connector
/connectors /custom /{custom_id}Change its name, address, sign-in or limits; send only what changes. A secret left out (or empty) keeps the saved one, and so does an extra header sent with an empty value. Agents use the change from their next message.
Full accessKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).
Body
namestringIts name.
base_urlstringAn API's address.
urlstringAn MCP server's address.
authobjectHow it signs in, as when connecting.
secretsobjectNew keys, as when connecting.
headersarrayAn API's extra headers: the whole list.
timeout_sintegerHow long to wait for an answer, 2 to 30 seconds (a voice call waits 5 at most).
calls_per_minuteintegerHow often agents may call it, 1 to 600 a minute.
curl -X PATCH https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"timeout_s": 10
}'{
"id": "b2d4f6a8-0c1e-4b3d-9f5a-7c9e1b3d5f7a",
"object": "custom_connector",
"kind": "api",
"name": "Orders",
"status": "live",
"needs_sign_in": false,
"address": "https://api.lumora.studio/v1",
"auth": {
"type": "api_key",
"in": "header",
"name": "X-API-Key"
},
"secrets_set": [
"api_key"
],
"headers": [],
"timeout_s": 10,
"calls_per_minute": 60,
"server": null,
"transport": null,
"check": {
"ok": true,
"status": 200,
"ms": 212,
"message": "Connected. The API answered in 212 ms.",
"at": "2026-11-01T10:00:00+00:00"
},
"tools_refreshed_at": null,
"tools": [
{
"id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
"object": "connector_tool",
"key": "get_order",
"name": "Look up an order",
"description": "When a customer asks where their order is, what's in it or when it arrives.",
"source": "openapi",
"enabled": true,
"changes": false,
"position": 0,
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
],
"fixed": [],
"fields": [
"id",
"status",
"items.name",
"delivery.expected"
],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": "2026-11-01T10:00:00+00:00",
"test_ok": true
},
{
"id": "a0c2e4b6-8d0f-4a2c-b4e6-8f0a2c4e6b8d",
"object": "connector_tool",
"key": "cancel_order",
"name": "Cancel an order",
"description": "When a customer asks to cancel an order that hasn't been sent yet.",
"source": "openapi",
"enabled": true,
"changes": true,
"position": 1,
"method": "POST",
"path": "/orders/{order_id}/cancel",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
},
{
"name": "reason",
"in": "body",
"type": "string",
"required": false,
"description": "Why the customer is cancelling, in their words.",
"enum": null,
"example": null
}
],
"fixed": [],
"fields": [],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": null,
"test_ok": null
}
],
"agents": [
{
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava",
"connector_id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"enabled": true,
"billing": "paid",
"status": "live"
}
],
"stats": {
"calls_7d": 1284,
"ok_7d": 1274,
"failed_7d": 10,
"avg_ms_7d": 310
},
"created_at": "2026-10-28T12:00:00+00:00",
"created_by": "Sam Rivera"
}Remove a custom connector
/connectors /custom /{custom_id}Removes it from your account with its keys, tools and activity. It's detached from every agent first; each agent detached within grace_hours of being charged gets its month back (refunded_usd, the total).
Full accessKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).
curl -X DELETE https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "b2d4f6a8-0c1e-4b3d-9f5a-7c9e1b3d5f7a",
"object": "custom_connector",
"deleted": true,
"refunded_usd": "0.000000"
}Test the connection
/connectors /custom /{custom_id} /checkCalls your system once and says whether it answered, and how fast. Any answer counts except a refused sign-in (401 or 403) or a server error. An MCP server's tools are listed again too: new ones start off. The result is kept as the connector's check.
Full accessKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).
curl -X POST https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/check \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "connector_check",
"ok": true,
"status": 200,
"ms": 212,
"message": "Connected. The API answered in 212 ms."
}List tools
/connectors /custom /{custom_id} /toolsIts tools, in order. An API tool has its request (method, path, inputs, fixed) and the reply agents see (fields, results_path, max_results); an MCP tool has the server's input_schema instead. enabled is whether agents may use it at all; each agent can switch tools off for itself (Customer Agents › Connectors, actions).
Any keyKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).
curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
"object": "connector_tool",
"key": "get_order",
"name": "Look up an order",
"description": "When a customer asks where their order is, what's in it or when it arrives.",
"source": "openapi",
"enabled": true,
"changes": false,
"position": 0,
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
],
"fixed": [],
"fields": [
"id",
"status",
"items.name",
"delivery.expected"
],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": "2026-11-01T10:00:00+00:00",
"test_ok": true
},
{
"id": "a0c2e4b6-8d0f-4a2c-b4e6-8f0a2c4e6b8d",
"object": "connector_tool",
"key": "cancel_order",
"name": "Cancel an order",
"description": "When a customer asks to cancel an order that hasn't been sent yet.",
"source": "openapi",
"enabled": true,
"changes": true,
"position": 1,
"method": "POST",
"path": "/orders/{order_id}/cancel",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
},
{
"name": "reason",
"in": "body",
"type": "string",
"required": false,
"description": "Why the customer is cancelling, in their words.",
"enum": null,
"example": null
}
],
"fixed": [],
"fields": [],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": null,
"test_ok": null
}
],
"has_more": false
}Add tools
/connectors /custom /{custom_id} /toolsAdds up to 100 tools to an API connector in one go (an API holds 100 at most). Agents that use the connector get them from their next message. Tools from an API description (Read an API description) can be sent as they come, after any changes.
Full accessKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).
Body
toolsarrayrequiredThe tools to add. Each is
{name, description, method, path, inputs, fixed, fields, results_path, max_results, changes, enabled}.nameis what people call it, anddescriptionsays when agents should use it, in plain words.methodisGET,POST,PUT,PATCHorDELETE, andpathstarts with/(each{name}in it needs apathinput).inputsare what the agent fills in:{name, in, type, required, description, enum, example, wire}, withinone ofquery,path,bodyorheaderandtypeone ofstring,number,integer,booleanorarray(a list of strings); a dotted body name (address.city) sends a nested value. An input'snameis up to 64 letters, digits,_,-and.; when your API uses another name, likepage[size]or$filter, put that inwireand it's sent instead (null or left out sendsname). A tool you get back haswireonly on the inputs that use one.fixedvalues ({name, in, value}) are always sent, and the agent never sees them.fieldsare the dotted paths of the reply agents see (empty for all of it),results_pathis where the list sits in the reply (null to find it), andmax_resultsis 1 to 50 (default 10).changes(default: true for anything butGET) makes the agent ask the customer to confirm before it runs. Akey(the tool's name for the AI, lower case and underscores) is made fromnamewhen left out.
curl -X POST https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tools": [
{
"name": "Look up an order",
"description": "When a customer asks where their order is, what's in it or when it arrives.",
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
]
}
]
}'{
"object": "list",
"data": [
{
"id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
"object": "connector_tool",
"key": "get_order",
"name": "Look up an order",
"description": "When a customer asks where their order is, what's in it or when it arrives.",
"source": "hand",
"enabled": true,
"changes": false,
"position": 0,
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
],
"fixed": [],
"fields": [],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": null,
"test_ok": null
}
],
"has_more": false
}Get a tool
/connectors /custom /{custom_id} /tools /{tool_id}One tool, with how its last test went (test_ok).
Any keyKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).tool_idstringrequiredThe tool's ID.
curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools/$TOOL_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
"object": "connector_tool",
"key": "get_order",
"name": "Look up an order",
"description": "When a customer asks where their order is, what's in it or when it arrives.",
"source": "openapi",
"enabled": true,
"changes": false,
"position": 0,
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
],
"fixed": [],
"fields": [
"id",
"status",
"items.name",
"delivery.expected"
],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": "2026-11-01T10:00:00+00:00",
"test_ok": true
}Update a tool
/connectors /custom /{custom_id} /tools /{tool_id}Change any part of an API tool, or switch any tool on or off (enabled) and say whether it changes things (changes). An MCP tool's request comes from the server, so it takes only name, description, enabled and changes: anything else is a 422.
Full accessKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).tool_idstringrequiredThe tool's ID.
Body
enabledbooleanAgents may use it.
changesbooleanIt creates, changes or deletes something: the customer confirms before it runs.
namestringIts name.
descriptionstringWhen agents should use it.
methodstringThe request's method (API tools).
pathstringThe request's path (API tools).
inputsarrayWhat the agent fills in: the whole list (API tools).
fixedarrayValues always sent: the whole list (API tools).
fieldsarrayThe reply's fields agents see; empty for all (API tools).
results_pathstringWhere the list sits in the reply (API tools).
max_resultsintegerResults agents get, 1 to 50 (API tools).
curl -X PATCH https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools/$TOOL_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fields": [
"id",
"status",
"delivery.expected"
]
}'{
"id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
"object": "connector_tool",
"key": "get_order",
"name": "Look up an order",
"description": "When a customer asks where their order is, what's in it or when it arrives.",
"source": "openapi",
"enabled": true,
"changes": false,
"position": 0,
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
],
"fixed": [],
"fields": [
"id",
"status",
"delivery.expected"
],
"results_path": null,
"max_results": 10,
"input_schema": null,
"tested_at": "2026-11-01T10:00:00+00:00",
"test_ok": true
}Remove a tool
/connectors /custom /{custom_id} /tools /{tool_id}Removes an API tool. Agents stop using it from their next message. An MCP server's tools come from the server: switch one off instead.
Full accessKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).tool_idstringrequiredThe tool's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools/$TOOL_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
"object": "connector_tool",
"deleted": true
}Test a tool
/connectors /custom /{custom_id} /tools /{tool_id} /testRuns the tool once, for real, with these values: a tool that changes things really does. You get the reply as it came (raw, cut at 20 KB), what an agent would get (shown, after fields and max_results), the reply's fields with an example each (for choosing fields), and how many results it found (count). It shows in the connector's activity.
Full accessKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).tool_idstringrequiredThe tool's ID.
Body
argumentsobjectThe tool's inputs, by name, like
{"order_id": "LS-1042"}.
curl -X POST https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools/$TOOL_ID/test \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"arguments": {
"order_id": "LS-1042"
}
}'{
"object": "tool_test",
"ok": true,
"status": 200,
"ms": 284,
"raw": {
"id": "LS-1042",
"status": "shipped",
"items": [
{
"name": "Lawn suit, 3 piece",
"sku": "LS-221",
"cost": 2100
}
],
"delivery": {
"expected": "2026-11-03",
"courier": "TCS"
},
"internal_note": "Repeat customer"
},
"fields": [
{
"path": "id",
"example": "LS-1042"
},
{
"path": "status",
"example": "shipped"
},
{
"path": "items.name",
"example": "Lawn suit, 3 piece"
},
{
"path": "items.sku",
"example": "LS-221"
},
{
"path": "items.cost",
"example": "2100"
},
{
"path": "delivery.expected",
"example": "2026-11-03"
},
{
"path": "delivery.courier",
"example": "TCS"
},
{
"path": "internal_note",
"example": "Repeat customer"
}
],
"shown": {
"ok": true,
"result": {
"id": "LS-1042",
"status": "shipped",
"items": [
{
"name": "Lawn suit, 3 piece"
}
],
"delivery": {
"expected": "2026-11-03"
}
}
}
}List calls
/connectors /custom /{custom_id} /activityIts tools' calls from the last 30 days, newest first, with the last 7 days in numbers (stats). source is agent (a customer conversation, with its channel), ask (Ask Marvoxa or Ask agent), test (the console) or api (Test a tool). status is ok, failed, waiting (a tool that changes things, waiting for the customer's yes), confirmed (the customer said yes, and the call ran as a new row) or blocked (the connector isn't live, too many calls, or a sign-in needed). Values that look secret are hidden in arguments.
Any keyKey that reaches this module
Path parameters
custom_idstringrequiredThe custom connector's ID (the same as its connection's
id).
Query parameters
limitintegerHow many, 1 to 200. Default 50.
beforestringCalls before this time (an earlier answer's last
at), for the next page.statusstringOnly
ok,failed,waiting,confirmedorblockedcalls. Name several with commas.toolstringOnly this tool's calls (its
key).
curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/activity?limit=20 \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "e8a0c2e4-6b8d-4fa1-b3c5-7e9a1c3e5b7d",
"object": "connector_call",
"at": "2026-11-01T10:00:00+00:00",
"tool_key": "get_order",
"tool_name": "Look up an order",
"status": "ok",
"http_status": 200,
"duration_ms": 284,
"error": null,
"source": "agent",
"channel": "whatsapp",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"agent_name": "Ava",
"conversation_id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"arguments": {
"order_id": "LS-1042"
}
}
],
"has_more": false,
"stats": {
"calls_7d": 1284,
"ok_7d": 1274,
"failed_7d": 10,
"avg_ms_7d": 310
}
}Read an API description
/connectors /importReads an OpenAPI (3.0 or 3.1) or Swagger (2.0) description, in JSON or YAML, into a draft tool for each operation, ready for Add tools. Nothing is saved. Send exactly one of url, text or file (up to 5 MB). It also suggests the API's address and how it signs in. Read operations come first; truncated is true when it had more than the 300 read.
Full accessKey that reaches this module
Body
urlstringA link to the description, like
https://api.yourcompany.com/openapi.json.textstringThe description itself.
fileobjectA file:
{name, data}, withdatain base64 or as a data URL.
curl -X POST https://ai-api.marvoxa.com/v1/connectors/import \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.lumora.studio/openapi.json"
}'{
"object": "api_description",
"title": "Lumora Studio Orders API",
"base_url": "https://api.lumora.studio/v1",
"auth": {
"type": "api_key",
"in": "header",
"name": "X-API-Key"
},
"operations": [
{
"op": "getOrder",
"key": "get_order",
"name": "Get order",
"description": "Returns one order by its number.",
"method": "GET",
"path": "/orders/{order_id}",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
}
],
"changes": false,
"tag": "Orders"
},
{
"op": "cancelOrder",
"key": "cancel_order",
"name": "Cancel order",
"description": "Cancels an order that hasn't been sent.",
"method": "POST",
"path": "/orders/{order_id}/cancel",
"inputs": [
{
"name": "order_id",
"in": "path",
"type": "string",
"required": true,
"description": "The order number, like LS-1042.",
"enum": null,
"example": "LS-1042"
},
{
"name": "reason",
"in": "body",
"type": "string",
"required": false,
"description": "Why the customer is cancelling, in their words.",
"enum": null,
"example": null
}
],
"changes": true,
"tag": "Orders"
}
],
"truncated": false
}Knowledge bases
Knowledge bases
In the portal: Brain › Knowledge
What your agents know, kept in knowledge bases on your account: text you write, web pages and files. Each agent answers from the knowledge bases attached to it (Customer Agents › Knowledge bases), and one knowledge base can serve many agents. Your package's words per knowledge base apply, as in the portal (word_limit, null with no limit). Needs a key that reaches this module.
List knowledge bases
/knowledge-basesEvery knowledge base, oldest first, with its size, where its documents came from, the agents reading it, and what needs a look (health: disagreements not settled, test questions and how many pass, documents that ended or can't be read again). made_for is the agent a knowledge base was made for, when it holds what was taught to that agent directly.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/knowledge-bases \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"name": "Shop policies",
"description": "Delivery, returns and payment.",
"made_for": null,
"documents": 4,
"words": 1840,
"sources": [
"Web page",
"Written"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"health": {
"conflicts": 0,
"tests": 2,
"passing": 2,
"ended": 0,
"sync_failed": 0
},
"created_at": "2026-10-12T09:30:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00"
}
],
"has_more": false,
"word_limit": 50000
}Create a knowledge base
/knowledge-basesA new, empty knowledge base. Up to 50 on an account.
Full accessKey that reaches this module
Body
namestringrequiredUp to 120 characters.
descriptionstringWhat's in it, up to 600 characters.
agent_idsstring[]Agents that read it from the start.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Shop policies",
"description": "Delivery, returns and payment.",
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
]
}'{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"name": "Shop policies",
"description": "Delivery, returns and payment.",
"made_for": null,
"documents": 0,
"words": 0,
"sources": [],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"health": {
"conflicts": 0,
"tests": 0,
"passing": 0,
"ended": 0,
"sync_failed": 0
},
"created_at": "2026-10-12T09:30:00+00:00",
"updated_at": "2026-10-12T09:30:00+00:00"
}Get a knowledge base
/knowledge-bases /{kb_id}One knowledge base, with its test questions and the documents in it that disagree.
Any keyKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"name": "Shop policies",
"description": "Delivery, returns and payment.",
"made_for": null,
"documents": 4,
"words": 1840,
"sources": [
"Web page",
"Written"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"health": {
"conflicts": 0,
"tests": 2,
"passing": 2,
"ended": 0,
"sync_failed": 0
},
"created_at": "2026-10-12T09:30:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00",
"word_limit": 50000,
"tests": [
{
"id": "cfecbcba5166",
"question": "Do you ship to Chicago?",
"expect": "2-4 business days",
"passed": true,
"found": "Delivery policy"
}
],
"tests_run_at": "2026-11-01T10:00:00+00:00",
"conflicts": [],
"checked_at": null
}Update a knowledge base
/knowledge-bases /{kb_id}Send only what changes. agent_ids sets exactly which agents read it.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
Body
namestringUp to 120 characters.
descriptionstringUp to 600 characters.
agent_idsstring[]Exactly these agents read it.
curl -X PATCH https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"8c2d4e6f-1a3b-4c5d-9e7f-2b4d6f8a0c1e"
]
}'{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"name": "Shop policies",
"description": "Delivery, returns and payment.",
"made_for": null,
"documents": 4,
"words": 1840,
"sources": [
"Web page",
"Written"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"8c2d4e6f-1a3b-4c5d-9e7f-2b4d6f8a0c1e"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
},
{
"id": "8c2d4e6f-1a3b-4c5d-9e7f-2b4d6f8a0c1e",
"name": "Bilal"
}
],
"health": {
"conflicts": 0,
"tests": 2,
"passing": 2,
"ended": 0,
"sync_failed": 0
},
"created_at": "2026-10-12T09:30:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00"
}Delete a knowledge base
/knowledge-bases /{kb_id}Deletes it and every document in it. Agents reading it stop at once. This can't be undone.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"deleted": true
}Documents
In the portal: Brain › Knowledge › a knowledge base
What's in a knowledge base. Agents reading it use a change from their next reply.
List documents
/knowledge-bases /{kb_id} /documentsIts documents, oldest first, without their text (get one for that), and its words against your package's limit.
Any keyKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"agent_id": null,
"title": "Delivery policy",
"kind": "Policy",
"words": 64,
"source": null,
"resync": null,
"created_at": "2026-11-01T10:00:00+00:00",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e"
}
],
"has_more": false,
"words": 1840,
"word_limit": 50000
}Add a document
/knowledge-bases /{kb_id} /documentsA document from your own text.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
Body
titlestringrequiredUp to 200 characters.
contentstringrequiredThe text, up to 100,000 characters.
kindstringWhat it is, in your words (
Menu,Delivery policy). Defaulttext.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Delivery policy",
"content": "We ship across the US in 2-4 business days, and same day in New York City. Shipping is free over $80.",
"kind": "Policy"
}'{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"agent_id": null,
"title": "Delivery policy",
"kind": "Policy",
"words": 64,
"source": null,
"resync": null,
"created_at": "2026-11-01T10:00:00+00:00",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"content": "We ship across the US in 2-4 business days, and same day in New York City. Shipping is free over $80."
}Import a web page
/knowledge-bases /{kb_id} /documents /importReads a web page (or a link to a PDF) now and keeps it as a document. Read it again later with resync.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
Body
urlstringrequiredThe page's address.
kindstringWhat it is, in your words (
Menu,Delivery policy). Defaulttext.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/import \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://lumora.studio/delivery"
}'{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"agent_id": null,
"title": "Delivery policy",
"kind": "text",
"words": 64,
"source": "https://lumora.studio/delivery",
"resync": "web",
"created_at": "2026-11-01T10:00:00+00:00",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"content": "Delivery\n\nWe ship across the US..."
}Upload a file
/knowledge-bases /{kb_id} /documents /uploadReads a file now and keeps it as a document: .pdf, .docx, .txt, .md or .csv, up to about 5 MB.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
Body
namestringrequiredThe file's name, with its extension.
datastringrequiredThe file as base64 (or a data URL).
kindstringWhat it is, in your words (
Menu,Delivery policy). Defaulttext.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/upload \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "price-list.txt",
"data": "S3VydGEgUnMgMiw1MDA="
}'{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"agent_id": null,
"title": "price-list.txt",
"kind": "text",
"words": 3,
"source": "price-list.txt",
"resync": null,
"created_at": "2026-11-01T10:00:00+00:00",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"content": "Linen shirt $64"
}Get a document
/knowledge-bases /{kb_id} /documents /{doc_id}One document, with its text.
Any keyKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
doc_idstringrequiredThe document's ID.
curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/$DOC_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"agent_id": null,
"title": "Delivery policy",
"kind": "Policy",
"words": 64,
"source": null,
"resync": null,
"created_at": "2026-11-01T10:00:00+00:00",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"content": "We ship across the US..."
}Update a document
/knowledge-bases /{kb_id} /documents /{doc_id}Send only what changes.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
doc_idstringrequiredThe document's ID.
Body
titlestringUp to 200 characters.
contentstringUp to 100,000 characters.
kindstringWhat it is, in your words.
curl -X PATCH https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/$DOC_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "We ship across the US in 2-4 business days. Shipping is free over $75."
}'{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"agent_id": null,
"title": "Delivery policy",
"kind": "Policy",
"words": 64,
"source": null,
"resync": null,
"created_at": "2026-11-01T10:00:00+00:00",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"content": "We ship across the US in 2-4 business days. Shipping is free over $75."
}Read it again
/knowledge-bases /{kb_id} /documents /{doc_id} /resyncReads a web page or Shopify store document again from where it came from (resync isn't null).
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
doc_idstringrequiredThe document's ID.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/$DOC_ID/resync \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"agent_id": null,
"title": "Delivery policy",
"kind": "Policy",
"words": 64,
"source": "https://lumora.studio/delivery",
"resync": "web",
"created_at": "2026-11-01T10:00:00+00:00",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"content": "Delivery\n\nWe ship across the US..."
}Delete a document
/knowledge-bases /{kb_id} /documents /{doc_id}Agents stop using it at once.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
doc_idstringrequiredThe document's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/$DOC_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"deleted": true
}Search, tests and disagreements
In the portal: Brain › Knowledge › a knowledge base
Check what a knowledge base gives your agents: search it as an agent would, keep test questions that run again on every change, and settle documents that disagree.
Search it
/knowledge-bases /{kb_id} /searchThe passages a question finds in this knowledge base, best first, with how well each matched: what an agent reading it would be given. Costs nothing.
Any keyKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
Body
questionstringrequiredWhat a customer might ask, up to 500 characters.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/search \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Do you ship to Chicago?"
}'{
"object": "knowledge_search",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"passages": [
{
"document_id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"title": "Delivery policy",
"content": "Delivery policy\nWe ship across the US in 2-4 business days. Shipping is free over $80.",
"score": 1.284
}
]
}Add a test question
/knowledge-bases /{kb_id} /testsA question with what the answer should say. Every test runs now and again on each change: passed says whether the passages found hold expect. Up to 40.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
Body
questionstringrequiredUp to 300 characters.
expectstringrequiredA word or phrase the answer must have, up to 120 characters.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/tests \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Do you ship to Chicago?",
"expect": "2-4 business days"
}'{
"object": "knowledge_tests",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"tests": [
{
"id": "cfecbcba5166",
"question": "Do you ship to Chicago?",
"expect": "2-4 business days",
"passed": true,
"found": "Delivery policy"
}
],
"tests_run_at": "2026-11-01T10:00:00+00:00"
}Run the tests
/knowledge-bases /{kb_id} /tests /runRuns every test question again now.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/tests/run \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "knowledge_tests",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"tests": [
{
"id": "cfecbcba5166",
"question": "Do you ship to Chicago?",
"expect": "2-4 business days",
"passed": true,
"found": "Delivery policy"
}
],
"tests_run_at": "2026-11-01T10:00:00+00:00"
}Delete a test question
/knowledge-bases /{kb_id} /tests /{test_id}It stops running.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
test_idstringrequiredThe test question's
id.
curl -X DELETE https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/tests/$TEST_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "cfecbcba5166",
"object": "knowledge_test",
"deleted": true
}Find documents that disagree
/knowledge-bases /{kb_id} /checkMarvoxa reads the documents for ones that say different things (choices already made are kept). Until a side is chosen, agents quote neither. Billed as knowledge help, an extra (price_usd).
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/check \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "knowledge_conflicts",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"conflicts": [
{
"id": "9a8b7c6d5e4f",
"topic": "Free delivery",
"a": {
"doc_id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"title": "Delivery policy",
"says": "Shipping is free over $80."
},
"b": {
"doc_id": "6a8c0e2f-4b6d-4f8a-9c0e-2b4d6f8a0c2e",
"title": "FAQ",
"says": "Shipping is free over $75."
},
"chosen": null
}
],
"checked_at": "2026-11-01T10:00:00+00:00",
"price_usd": "0.000420"
}Choose the right side
/knowledge-bases /{kb_id} /conflicts /{conflict_id}Which side of a disagreement is right. Agents use it from their next reply.
Full accessKey that reaches this module
Path parameters
kb_idstringrequiredThe knowledge base's ID.
conflict_idstringrequiredThe disagreement's
id.
Body
chosenstring | nullrequiredaorb, or null to undo the choice.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/conflicts/$CONFLICT_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chosen": "a"
}'{
"object": "knowledge_conflicts",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"conflicts": [
{
"id": "9a8b7c6d5e4f",
"topic": "Free delivery",
"a": {
"doc_id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"title": "Delivery policy",
"says": "Shipping is free over $80."
},
"b": {
"doc_id": "6a8c0e2f-4b6d-4f8a-9c0e-2b4d6f8a0c2e",
"title": "FAQ",
"says": "Shipping is free over $75."
},
"chosen": "a"
}
],
"checked_at": "2026-11-01T10:00:00+00:00"
}Knowledge gaps
In the portal: Brain › Knowledge › Gaps
Questions customers asked that no knowledge base answered. Marvoxa drafts answers from your team's replies; you check them and add them to a knowledge base as a question and answer. Needs a key that reaches this module.
List gaps
/knowledge-gapsMost asked first. status is drafted (an answer is written, waiting for your OK), needs (your answer) or added. Dismissed ones aren't listed.
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/knowledge-gaps \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "f2b4d6f8-0a2c-4e6a-9b8d-0f2a4c6e8b0d",
"object": "knowledge_gap",
"question": "Do you deliver on Sundays?",
"answer": "Yes, in New York City and Chicago.",
"asked": 6,
"source": "From replies by Nora in Conversations",
"conversation_ids": [
"a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d"
],
"status": "drafted",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"document_id": null,
"created_at": "2026-11-01T10:00:00+00:00"
}
],
"has_more": false,
"scanned_at": "2026-11-01T10:00:00+00:00"
}Find gaps
/knowledge-gaps /scanMarvoxa reads the last week's conversations where your team stepped in and drafts answers to what the knowledge bases couldn't answer. Billed as knowledge help, an extra (price_usd).
Full accessKey that reaches this module
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-gaps/scan \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "knowledge_gap_scan",
"added": 2,
"price_usd": "0.000910"
}Update a gap
/knowledge-gaps /{gap_id}Correct the question or answer, or choose the knowledge base it goes in. Send only what changes.
Full accessKey that reaches this module
Path parameters
gap_idstringrequiredThe gap's ID.
Body
questionstringUp to 300 characters.
answerstringUp to 2,000 characters.
knowledge_base_idstringThe knowledge base it goes in.
curl -X PATCH https://ai-api.marvoxa.com/v1/knowledge-gaps/$GAP_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"answer": "Yes, in New York City, Chicago and Boston."
}'{
"id": "f2b4d6f8-0a2c-4e6a-9b8d-0f2a4c6e8b0d",
"object": "knowledge_gap",
"question": "Do you deliver on Sundays?",
"answer": "Yes, in New York City, Chicago and Boston.",
"asked": 6,
"source": "From replies by Nora in Conversations",
"conversation_ids": [
"a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d"
],
"status": "drafted",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"document_id": null,
"created_at": "2026-11-01T10:00:00+00:00"
}Add it to its knowledge base
/knowledge-gaps /{gap_id} /addAdds the answer as a question-and-answer document (document_id). It needs an answer and a knowledge base.
Full accessKey that reaches this module
Path parameters
gap_idstringrequiredThe gap's ID.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-gaps/$GAP_ID/add \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "f2b4d6f8-0a2c-4e6a-9b8d-0f2a4c6e8b0d",
"object": "knowledge_gap",
"question": "Do you deliver on Sundays?",
"answer": "Yes, in New York City, Chicago and Boston.",
"asked": 6,
"source": "From replies by Nora in Conversations",
"conversation_ids": [
"a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d"
],
"status": "added",
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"document_id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"created_at": "2026-11-01T10:00:00+00:00"
}Dismiss a gap
/knowledge-gaps /{gap_id} /dismissIt isn't listed again.
Full accessKey that reaches this module
Path parameters
gap_idstringrequiredThe gap's ID.
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-gaps/$GAP_ID/dismiss \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "f2b4d6f8-0a2c-4e6a-9b8d-0f2a4c6e8b0d",
"object": "knowledge_gap",
"deleted": true
}Customer Agents
Customer Agents › Agents
Agents
In the portal: Customer Agents, and each agent's Settings
Your customer agents. Each one has its own channels, conversations, workflows and settings under /agents/{agent_id}, and answers from the knowledge bases and connectors attached to it. A key limited to some agents only sees those.
curl https://ai-api.marvoxa.com/v1/agents \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"object": "agent",
"name": "Ava",
"greeting": "Hi! How can I help?",
"language": "auto",
"status": "live",
"created_at": "2026-10-12T09:30:00+00:00",
"enabled": true,
"avatar_url": null,
"tier": "standard"
}
],
"has_more": false
}Create an agent
/agentsA new agent, with website chat ready to add to your site. It answers once your account has a running package.
Full accessKey that reaches this module
Body
namestringrequiredIts name, up to 80 characters.
languagestringauto(answers in the customer's language),en,urorroman-ur. Defaultauto.greetingstringIts first message, up to 300 characters.
instructionsstringAnything it should always know or do.
websitesstring[]Websites its chat may load on (
lumora.studio), up to 20.
curl -X POST https://ai-api.marvoxa.com/v1/agents \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Ava",
"greeting": "Hi! How can I help?"
}'{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"object": "agent",
"name": "Ava",
"greeting": "Hi! How can I help?",
"language": "auto",
"status": "live",
"created_at": "2026-10-12T09:30:00+00:00",
"enabled": true,
"avatar_url": null,
"tier": "standard"
}Get an agent
/agents /{agent_id}One agent. status is live, off (paused) or draft (still being set up).
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"object": "agent",
"name": "Ava",
"greeting": "Hi! How can I help?",
"language": "auto",
"status": "live",
"created_at": "2026-10-12T09:30:00+00:00",
"enabled": true,
"avatar_url": null,
"tier": "standard"
}Update an agent
/agents /{agent_id}The agent's Settings page. Send only what changes. enabled: false pauses it on every channel.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
namestringUp to 80 characters.
languagestringauto,en,urorroman-ur.greetingstringUp to 300 characters.
enabledbooleanAnswering customers (true) or paused (false).
curl -X PATCH https://ai-api.marvoxa.com/v1/agents/$AGENT_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"greeting": "Hi! How can I help?"
}'{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"object": "agent",
"name": "Ava",
"greeting": "Hi! How can I help?",
"language": "auto",
"status": "live",
"created_at": "2026-10-12T09:30:00+00:00",
"enabled": true,
"avatar_url": null,
"tier": "standard"
}Set its picture
/agents /{agent_id} /avatarThe picture customers see in the chat. Send a data URL (PNG, JPG or WebP, up to about 5 MB), or null to remove it.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
imagestring | nullrequireddata:image/png;base64,..., or null to remove it.
curl -X PUT https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/avatar \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": null
}'{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"object": "agent",
"name": "Ava",
"greeting": "Hi! How can I help?",
"language": "auto",
"status": "live",
"created_at": "2026-10-12T09:30:00+00:00",
"enabled": true,
"avatar_url": null,
"tier": "standard"
}Delete an agent
/agents /{agent_id}Deletes the agent: its channels and connectors stop, and the knowledge base made for it is removed. This can't be undone. An agent that has answered customers needs its name in confirm. Keys and webhooks limited to it stop reaching it.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Query parameters
confirmstringThe agent's name, exactly. Needed once it has answered customers.
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID?confirm=Ava \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"object": "agent",
"deleted": true
}Talk to an agent
In the portal: As a customer, from your own site or app
Put your agent in your own website, app or system: send what a customer says and get the agent's reply, with the same knowledge, workflows and hand-off as on your other channels.
Send a message
/agents /{agent_id} /messagesSends a customer's message to your agent and returns its reply. Set stream to get the reply as it's written, as server-sent events.
Messages and read, or full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
messagestringrequiredWhat the customer said. Up to 2,000 characters.
conversation_idstringCarry on this conversation. Leave it out to start a new one.
userstringYour own ID for the person, up to 100 characters.
streambooleanStream the reply as server-sent events:
conversation, thendeltapieces of text, thendonewith the whole message (orerror).
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/messages \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Hi! Do you ship to Chicago?",
"user": "customer-42"
}'{
"id": "6d0f3c2a-91b7-4a5e-8f4d-3b2c1a0e9d8f",
"object": "message",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"conversation_id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"status": "answered",
"reply": "Yes! We ship to Chicago in 2-4 business days. Shipping is free over $80.",
"handoff": false,
"usage": {
"charge": "included",
"price_usd": "0",
"input_tokens": 1240,
"output_tokens": 32
}
}Customer Agents › Conversations
Conversations
In the portal: Customer Agents › agent › Conversations
Your agent's customer conversations on every channel. With a full-access key, your own system can take one over, reply as your team and hand it back, as in the portal's Inbox.
List conversations
/agents /{agent_id} /conversationsNewest first, on every channel: website chat (web), website voice calls (call), WhatsApp and the API.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Query parameters
channelstringOnly one channel:
web,whatsapp,callorapi.userstringOnly this person's API conversations.
limitintegerHow many, 1 to 100. Default 20.
beforetimestampFor the next page: the last conversation's
last_message_at.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations?limit=20 \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"object": "conversation",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"channel": "api",
"user": "customer-42",
"status": "open",
"human": null,
"workflow_id": null,
"details": {},
"message_count": 2,
"created_at": "2026-11-01T10:00:00+00:00",
"last_message_at": "2026-11-01T10:00:02+00:00"
}
],
"has_more": false
}Get a conversation
/agents /{agent_id} /conversations /{conversation_id}One conversation, whether your team has it (human: asked or taken), and the workflow it follows with the details collected for it (workflow_id, details).
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
conversation_idstringrequiredThe conversation's ID.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"object": "conversation",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"channel": "api",
"user": "customer-42",
"status": "open",
"human": null,
"workflow_id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"details": {
"name": "Jordan",
"phone_number": "(312) 555-0142"
},
"message_count": 2,
"created_at": "2026-11-01T10:00:00+00:00",
"last_message_at": "2026-11-01T10:00:02+00:00"
}List messages
/agents /{agent_id} /conversations /{conversation_id} /messagesA page of a conversation, oldest first: the customer (user), your agent (assistant) and your team (staff).
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
conversation_idstringrequiredThe conversation's ID.
Query parameters
limitintegerHow many, 1 to 100. Default 50.
beforestringFor older messages: the first message's ID from the last page.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/messages \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "1b2c…",
"object": "message",
"role": "user",
"text": "Hi! Do you ship to Chicago?",
"via": "chat",
"created_at": "2026-11-01T10:00:00+00:00"
},
{
"id": "6d0f…",
"object": "message",
"role": "assistant",
"text": "Yes! We ship to Chicago in 2-4 business days.",
"via": "chat",
"created_at": "2026-11-01T10:00:02+00:00"
}
],
"has_more": false
}Take it over
/agents /{agent_id} /conversations /{conversation_id} /takeYour team takes the conversation: the agent goes quiet in it until it's handed back, and replies come from you.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
conversation_idstringrequiredThe conversation's ID.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/take \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"object": "conversation",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"channel": "api",
"user": "customer-42",
"status": "open",
"human": "taken",
"workflow_id": null,
"details": {},
"message_count": 2,
"created_at": "2026-11-01T10:00:00+00:00",
"last_message_at": "2026-11-01T10:00:02+00:00",
"human_by": "API key Website backend"
}Reply as your team
/agents /{agent_id} /conversations /{conversation_id} /replySends your team's reply on the conversation's channel: website chat, WhatsApp (within 24 hours of the customer's last message), email or a text. On an API conversation it's saved for your app to show (sent_via: "api"). Takes the conversation over if it wasn't yet. A call isn't replied to in writing (409): someone from your team joins it from the portal.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
conversation_idstringrequiredThe conversation's ID.
Body
textstringrequiredUp to 4,000 characters.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/reply \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hi Jordan, this is Nora. Your order leaves today."
}'{
"id": "7e1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
"object": "message",
"role": "staff",
"text": "Hi Jordan, this is Nora. Your order leaves today.",
"via": null,
"created_at": "2026-11-01T10:00:00+00:00",
"conversation_id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"sent_via": "whatsapp"
}Hand it back
/agents /{agent_id} /conversations /{conversation_id} /releaseHands the conversation back to the agent.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
conversation_idstringrequiredThe conversation's ID.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/release \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"object": "conversation",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"channel": "api",
"user": "customer-42",
"status": "open",
"human": null,
"workflow_id": null,
"details": {},
"message_count": 2,
"created_at": "2026-11-01T10:00:00+00:00",
"last_message_at": "2026-11-01T10:00:02+00:00",
"human_by": null
}Leads
In the portal: Customer Agents › agent › Leads
People who left their details with your agent. A workflow saves every detail it asks for (source: "workflow"); otherwise, when a customer types a phone number or email in a conversation, it's picked up as a lead (source: "chat") if the agent's lead setting is on. One lead per conversation, filled in as the customer says more. New leads also arrive as the lead.created webhook.
List leads
/agents /{agent_id} /leadsNewest first. interest is the customer's first message; details is everything a workflow saved, labelled by its fields. If your account hides customers' phone numbers, phone is masked here too.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Query parameters
statusstringOnly one status:
new,contacted,wonorlost.sourcestringworkfloworchat.channelstringOnly one channel:
web,call,whatsapporapi.qstringSearch names, phone numbers, emails, what they asked, details and notes.
sincedateFrom this day (YYYY-MM-DD, Pakistan time), included.
untildateUp to this day, included.
limitintegerHow many, 1 to 100. Default 20.
beforetimestampFor the next page: the last lead's
created_at.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads?status=new&limit=20 \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d5f",
"object": "lead",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"conversation_id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"workflow_id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"source": "workflow",
"channel": "whatsapp",
"name": "Jordan Lee",
"phone": "+13125550142",
"email": "jordan@example.com",
"interest": "Do you have the linen shirt in white, size M?",
"details": [
{
"key": "name",
"label": "Name",
"value": "Jordan Lee"
},
{
"key": "phone_number",
"label": "Phone number",
"value": "+13125550142"
},
{
"key": "city",
"label": "City",
"value": "Chicago"
}
],
"status": "new",
"note": "",
"created_at": "2026-11-01T10:00:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00"
}
],
"has_more": false
}Get lead settings
/agents /{agent_id} /leads /settingscapture: the agent saves a lead when a customer types a phone number or email. Workflows save the details they ask for either way.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/settings \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "lead_settings",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"capture": true
}Update lead settings
/agents /{agent_id} /leads /settingsTurns picking up leads from conversations on or off.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
capturebooleanrequiredOn or off.
curl -X PATCH https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/settings \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"capture": false
}'{
"object": "lead_settings",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"capture": false
}Get a lead
/agents /{agent_id} /leads /{lead_id}One lead.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
lead_idstringrequiredThe lead's ID.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/$LEAD_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d5f",
"object": "lead",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"conversation_id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"workflow_id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"source": "workflow",
"channel": "whatsapp",
"name": "Jordan Lee",
"phone": "+13125550142",
"email": "jordan@example.com",
"interest": "Do you have the linen shirt in white, size M?",
"details": [
{
"key": "name",
"label": "Name",
"value": "Jordan Lee"
},
{
"key": "phone_number",
"label": "Phone number",
"value": "+13125550142"
},
{
"key": "city",
"label": "City",
"value": "Chicago"
}
],
"status": "new",
"note": "",
"created_at": "2026-11-01T10:00:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00"
}Update a lead
/agents /{agent_id} /leads /{lead_id}Moves a lead along and keeps your team's note, as in the portal. Send only what changes; correct the contact details if the customer got one wrong.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
lead_idstringrequiredThe lead's ID.
Body
statusstringnew,contacted,wonorlost.notestringYour team's note, up to 4,000 characters.
namestringUp to 160 characters.
phonestringUp to 40 characters.
emailstringUp to 200 characters.
curl -X PATCH https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/$LEAD_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "contacted",
"note": "Called, sending a quote."
}'{
"id": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d5f",
"object": "lead",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"conversation_id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"workflow_id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"source": "workflow",
"channel": "whatsapp",
"name": "Jordan Lee",
"phone": "+13125550142",
"email": "jordan@example.com",
"interest": "Do you have the linen shirt in white, size M?",
"details": [
{
"key": "name",
"label": "Name",
"value": "Jordan Lee"
},
{
"key": "phone_number",
"label": "Phone number",
"value": "+13125550142"
},
{
"key": "city",
"label": "City",
"value": "Chicago"
}
],
"status": "contacted",
"note": "Called, sending a quote.",
"created_at": "2026-11-01T10:00:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00"
}Delete a lead
/agents /{agent_id} /leads /{lead_id}Removes the lead. The conversation it came from stays.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
lead_idstringrequiredThe lead's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/$LEAD_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d5f",
"object": "lead",
"deleted": true
}Customer Agents › Teach
Knowledge bases
In the portal: Customer Agents › agent › Teach › Knowledge
The knowledge bases an agent answers from. Attach any of your account's knowledge bases (see Knowledge bases), up to 20 an agent, or let Marvoxa choose the ones its job needs. Attaching, setting and choosing need a key that reaches Knowledge too; a key for some agents sees only the agents it reaches in agent_ids and agents.
List attached knowledge bases
/agents /{agent_id} /knowledge-basesIn the order they were attached. words is what the agent reads from all of them.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/knowledge-bases \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"name": "Shop policies",
"description": "Delivery, returns and payment.",
"made_for": null,
"documents": 4,
"words": 1840,
"sources": [
"Web page",
"Written"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"health": {
"conflicts": 0,
"tests": 2,
"passing": 2,
"ended": 0,
"sync_failed": 0
},
"created_at": "2026-10-12T09:30:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00"
}
],
"has_more": false,
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"words": 1840,
"word_limit": 50000
}Attach a knowledge base
/agents /{agent_id} /knowledge-basesThe agent answers from it from its next reply. Returns the knowledge base, with this agent in agent_ids.
Full accessKey that reaches this module
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
knowledge_base_idstringrequiredOne of your account's knowledge bases.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/knowledge-bases \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"knowledge_base_id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e"
}'{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"name": "Shop policies",
"description": "Delivery, returns and payment.",
"made_for": null,
"documents": 4,
"words": 1840,
"sources": [
"Web page",
"Written"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"health": {
"conflicts": 0,
"tests": 2,
"passing": 2,
"ended": 0,
"sync_failed": 0
},
"created_at": "2026-10-12T09:30:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00"
}Set its knowledge bases
/agents /{agent_id} /knowledge-basesExactly these knowledge bases, in this order; any others are detached.
Full accessKey that reaches this module
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
knowledge_base_idsstring[]requiredUp to 20.
curl -X PUT https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/knowledge-bases \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"knowledge_base_ids": [
"c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e"
]
}'{
"object": "list",
"data": [
{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"name": "Shop policies",
"description": "Delivery, returns and payment.",
"made_for": null,
"documents": 4,
"words": 1840,
"sources": [
"Web page",
"Written"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"health": {
"conflicts": 0,
"tests": 2,
"passing": 2,
"ended": 0,
"sync_failed": 0
},
"created_at": "2026-10-12T09:30:00+00:00",
"updated_at": "2026-11-01T10:00:00+00:00"
}
],
"has_more": false,
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"words": 1840,
"word_limit": 50000
}Detach a knowledge base
/agents /{agent_id} /knowledge-bases /{kb_id}The agent stops reading it. The knowledge base stays on your account, for other agents.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
kb_idstringrequiredThe knowledge base's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/knowledge-bases/$KB_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
"object": "knowledge_base",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"detached": true
}Let Marvoxa choose
/agents /{agent_id} /knowledge-bases /chooseMarvoxa picks the knowledge bases this agent needs from its job, and names up to 3 topics none of them covers (missing). Nothing changes until you attach them (Set its knowledge bases). Billed as knowledge help, an extra (price_usd).
Full accessKey that reaches this module
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/knowledge-bases/choose \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "knowledge_base_choice",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"knowledge_base_ids": [
"c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e"
],
"why": "Customers ask about delivery and returns.",
"missing": [
"Opening hours"
],
"price_usd": "0.000133"
}Connectors
In the portal: Customer Agents › agent › Teach › Connectors
The account's connections (apps and your own systems, see Connectors) attached to an agent, so it can use them with customers. Attaching one is free on every package (price_monthly_usd is 0.00). kind is app, or api or mcp for your own system (with no app): its actions are its tools. An action's off is true when it's a tool switched off on the custom connector itself (Update a tool, enabled). The agent doesn't use it, whatever its own enabled says, until the tool is switched on again. Until you switch a custom connector's action for an agent, its enabled follows the tool's switch on the connector.
List attached connectors
/agents /{agent_id} /connectorsThe connectors attached to the agent, each with the account connection it comes from (connection_id) and what it may do (actions).
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"object": "connector",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Google Sheets",
"kind": "app",
"app": "googlesheets",
"status": "live",
"enabled": true,
"actions": [
{
"key": "GOOGLESHEETS_BATCH_UPDATE",
"name": "Write rows to a sheet",
"enabled": true,
"off": false
},
{
"key": "GOOGLESHEETS_BATCH_GET",
"name": "Read a sheet",
"enabled": true,
"off": false
}
],
"billing": "free",
"price_monthly_usd": "0.00",
"paid_until": null,
"created_at": "2026-11-01T10:00:00+00:00",
"connection_id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e"
}
],
"has_more": false,
"price_per_agent_monthly_usd": "0.00"
}Attach a connector
/agents /{agent_id} /connectorsAttaches a live connection to the agent, free. The same connection can't be attached to one agent twice (409).
Full accessKey that reaches this module
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
connection_idstringrequiredA live connection, from List connections.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connection_id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e"
}'{
"id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"object": "connector",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Google Sheets",
"kind": "app",
"app": "googlesheets",
"status": "live",
"enabled": true,
"actions": [
{
"key": "GOOGLESHEETS_BATCH_UPDATE",
"name": "Write rows to a sheet",
"enabled": true,
"off": false
},
{
"key": "GOOGLESHEETS_BATCH_GET",
"name": "Read a sheet",
"enabled": true,
"off": false
}
],
"billing": "free",
"price_monthly_usd": "0.00",
"paid_until": null,
"created_at": "2026-11-01T10:00:00+00:00",
"connection_id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e"
}Get a connector
/agents /{agent_id} /connectors /{connector_id}One attached app and what the agent may do with it.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
connector_idstringrequiredThe connector's ID.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors/$CONNECTOR_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"object": "connector",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Google Sheets",
"kind": "app",
"app": "googlesheets",
"status": "live",
"enabled": true,
"actions": [
{
"key": "GOOGLESHEETS_BATCH_UPDATE",
"name": "Write rows to a sheet",
"enabled": true,
"off": false
},
{
"key": "GOOGLESHEETS_BATCH_GET",
"name": "Read a sheet",
"enabled": true,
"off": false
}
],
"billing": "free",
"price_monthly_usd": "0.00",
"paid_until": null,
"created_at": "2026-11-01T10:00:00+00:00",
"connection_id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e"
}Update a connector
/agents /{agent_id} /connectors /{connector_id}Switch the app on or off for this agent, or some of its actions. Only the actions you name change. An action with off true keeps the enabled you give it, but isn't used until its tool is switched on again on the connector.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
connector_idstringrequiredThe connector's ID.
Body
enabledbooleanThe agent may use the app.
actionsobject{"ACTION_KEY": false}: switch actions on (true) or off (false), by theirkey.
curl -X PATCH https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors/$CONNECTOR_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"actions": {
"GOOGLESHEETS_BATCH_UPDATE": false
}
}'{
"id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"object": "connector",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Google Sheets",
"kind": "app",
"app": "googlesheets",
"status": "live",
"enabled": true,
"actions": [
{
"key": "GOOGLESHEETS_BATCH_UPDATE",
"name": "Write rows to a sheet",
"enabled": false,
"off": false
},
{
"key": "GOOGLESHEETS_BATCH_GET",
"name": "Read a sheet",
"enabled": true,
"off": false
}
],
"billing": "free",
"price_monthly_usd": "0.00",
"paid_until": null,
"created_at": "2026-11-01T10:00:00+00:00",
"connection_id": "e1a3c5e7-9b1d-4f3a-8c5e-7a9b1d3f5c7e"
}Detach a connector
/agents /{agent_id} /connectors /{connector_id}The agent stops using the app. It stays connected to your account for your other agents. Detached within a day of being charged, its month is given back (refunded_usd).
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
connector_idstringrequiredThe connector's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors/$CONNECTOR_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "7b9d1f3a-5c7e-4b9d-8f1a-3c5e7a9b1d3f",
"object": "connector",
"deleted": true,
"refunded_usd": "2.000000"
}Workflows
In the portal: Customer Agents › agent › Teach › Workflows
Set patterns your agent follows with customers, step by step, on the channels you give each one: take an order, book an appointment, qualify a lead. Without one, a channel answers normally from the agent's knowledge. Up to 50 per agent.
List workflows
/agents /{agent_id} /workflowsEach workflow, the details it asks for (fields) and how many conversations have followed it.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"object": "workflow",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"name": "Take an order",
"goal": "Help the customer choose, take their details and confirm the order.",
"enabled": true,
"type": "chat",
"steps": [
{
"id": "a1b2c3d4",
"kind": "say",
"title": "Welcome",
"text": "Greet them warmly and ask what they'd like to order."
},
{
"id": "e5f6a7b8",
"kind": "ask",
"title": "Who it's for",
"text": "",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
]
},
{
"id": "c9d0e1f2",
"kind": "do",
"title": "Send the order to our system",
"text": "",
"action": "webhook"
},
{
"id": "a3b4c5d6",
"kind": "end",
"title": "Thank them",
"text": "Confirm the order and say we'll call to confirm delivery."
}
],
"channels": [
"chat",
"whatsapp"
],
"updated_at": "2026-11-01T10:00:00+00:00",
"updated_by": "Sam Rivera",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
],
"conversations": 37
}
],
"has_more": false
}List workflow channels
/agents /{agent_id} /workflows /channelsEach channel, the kind of workflow it takes (type: chat or voice) and the workflow it follows (workflow_id is null when it answers normally). connected says whether the agent has that channel set up.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/channels \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"object": "workflow_channel",
"channel": "chat",
"name": "Website chat",
"type": "chat",
"workflow_id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"connected": true
},
{
"object": "workflow_channel",
"channel": "web_call",
"name": "Website voice calls",
"type": "voice",
"workflow_id": null,
"connected": true
},
{
"object": "workflow_channel",
"channel": "whatsapp",
"name": "WhatsApp",
"type": "chat",
"workflow_id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"connected": true
},
{
"object": "workflow_channel",
"channel": "api",
"name": "Developer API",
"type": "chat",
"workflow_id": null,
"connected": true
}
],
"has_more": false
}List templates
/agents /{agent_id} /workflows /templatesReady-made workflows to start from: order, booking and lead. Pass a key as template when you create one.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/templates \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"object": "workflow_template",
"key": "order",
"name": "Take an order",
"goal": "Help the customer choose, take their details and confirm the order.",
"steps": [
{
"id": "a1b2c3d4",
"kind": "say",
"title": "Welcome",
"text": "Greet them warmly and ask what they'd like to order."
},
{
"id": "e5f6a7b8",
"kind": "ask",
"title": "Who it's for",
"text": "",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
]
},
{
"id": "c9d0e1f2",
"kind": "do",
"title": "Send the order to our system",
"text": "",
"action": "webhook"
},
{
"id": "a3b4c5d6",
"kind": "end",
"title": "Thank them",
"text": "Confirm the order and say we'll call to confirm delivery."
}
]
}
],
"has_more": false
}Create a workflow
/agents /{agent_id} /workflowsFrom a template, from your own steps, or blank. moved_from lists other workflows a channel was taken from.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
typestringWhat it's for:
chat(the agent writes) orvoice(calls: the agent speaks). Its channels must be that kind. Leave it out and it's worked out fromchannels. Workflows made before this can benull: on both kinds.templatestringStart from a template:
order,bookingorlead.namestringUp to 120 characters.
goalstringWhat it's for, up to 600 characters.
stepsobject[]The steps, in order. Each is
{id, kind, title, text}withkindone ofsay,ask,decide,doorend. Anaskstep hasfields({label, kind, required, options}, wherekindistext,phone,email,number,date,addressorchoice). Adecidestep hasbranches({when, goto}). Adostep has anaction:savethe details, hand to aperson, use anapp(its name inapp), send to yourwebhookendpoints, orother.next(a step'sid) jumps; empty goes to the next step.channelsstring[]Where it's followed:
chat(website chat),web_call(website voice calls),whatsapp,api(this API). All of the workflow'stype:web_callis forvoice, the rest forchat. A channel follows one workflow at a time, so it's taken off any other.enabledbooleanOn (default) or off.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "chat",
"template": "order",
"channels": [
"chat",
"whatsapp"
]
}'{
"object": "workflow",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"name": "Take an order",
"goal": "Help the customer choose, take their details and confirm the order.",
"enabled": true,
"type": "chat",
"steps": [
{
"id": "a1b2c3d4",
"kind": "say",
"title": "Welcome",
"text": "Greet them warmly and ask what they'd like to order."
},
{
"id": "e5f6a7b8",
"kind": "ask",
"title": "Who it's for",
"text": "",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
]
},
{
"id": "c9d0e1f2",
"kind": "do",
"title": "Send the order to our system",
"text": "",
"action": "webhook"
},
{
"id": "a3b4c5d6",
"kind": "end",
"title": "Thank them",
"text": "Confirm the order and say we'll call to confirm delivery."
}
],
"channels": [
"chat",
"whatsapp"
],
"updated_at": "2026-11-01T10:00:00+00:00",
"updated_by": "Sam Rivera",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
],
"moved_from": []
}Get a workflow
/agents /{agent_id} /workflows /{workflow_id}One workflow with all its steps.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
workflow_idstringrequiredThe workflow's ID.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "workflow",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"name": "Take an order",
"goal": "Help the customer choose, take their details and confirm the order.",
"enabled": true,
"type": "chat",
"steps": [
{
"id": "a1b2c3d4",
"kind": "say",
"title": "Welcome",
"text": "Greet them warmly and ask what they'd like to order."
},
{
"id": "e5f6a7b8",
"kind": "ask",
"title": "Who it's for",
"text": "",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
]
},
{
"id": "c9d0e1f2",
"kind": "do",
"title": "Send the order to our system",
"text": "",
"action": "webhook"
},
{
"id": "a3b4c5d6",
"kind": "end",
"title": "Thank them",
"text": "Confirm the order and say we'll call to confirm delivery."
}
],
"channels": [
"chat",
"whatsapp"
],
"updated_at": "2026-11-01T10:00:00+00:00",
"updated_by": "Sam Rivera",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
]
}Update a workflow
/agents /{agent_id} /workflows /{workflow_id}Send only what changes. steps replaces every step and is checked whole; channels replaces the channels it's on.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
workflow_idstringrequiredThe workflow's ID.
Body
namestringUp to 120 characters.
goalstringUp to 600 characters.
enabledbooleanOn or off.
typestringchatorvoice. Change it withchannelsof that kind.stepsobject[]The steps, in order. Each is
{id, kind, title, text}withkindone ofsay,ask,decide,doorend. Anaskstep hasfields({label, kind, required, options}, wherekindistext,phone,email,number,date,addressorchoice). Adecidestep hasbranches({when, goto}). Adostep has anaction:savethe details, hand to aperson, use anapp(its name inapp), send to yourwebhookendpoints, orother.next(a step'sid) jumps; empty goes to the next step.channelsstring[]Where it's followed:
chat(website chat),web_call(website voice calls),whatsapp,api(this API). All of the workflow'stype:web_callis forvoice, the rest forchat. A channel follows one workflow at a time, so it's taken off any other.
curl -X PATCH https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channels": [
"chat",
"whatsapp",
"api"
]
}'{
"object": "workflow",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"name": "Take an order",
"goal": "Help the customer choose, take their details and confirm the order.",
"enabled": true,
"type": "chat",
"steps": [
{
"id": "a1b2c3d4",
"kind": "say",
"title": "Welcome",
"text": "Greet them warmly and ask what they'd like to order."
},
{
"id": "e5f6a7b8",
"kind": "ask",
"title": "Who it's for",
"text": "",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
]
},
{
"id": "c9d0e1f2",
"kind": "do",
"title": "Send the order to our system",
"text": "",
"action": "webhook"
},
{
"id": "a3b4c5d6",
"kind": "end",
"title": "Thank them",
"text": "Confirm the order and say we'll call to confirm delivery."
}
],
"channels": [
"chat",
"whatsapp",
"api"
],
"updated_at": "2026-11-01T10:00:00+00:00",
"updated_by": "Sam Rivera",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
],
"moved_from": []
}Duplicate a workflow
/agents /{agent_id} /workflows /{workflow_id} /duplicateA copy, on no channels, to change without touching the original.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
workflow_idstringrequiredThe workflow's ID.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID/duplicate \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "workflow",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"id": "8d9e0f1a-2b3c-4d5e-9f6a-7b8c9d0e1f2a",
"name": "Take an order (copy)",
"goal": "Help the customer choose, take their details and confirm the order.",
"enabled": true,
"type": "chat",
"steps": [
{
"id": "a1b2c3d4",
"kind": "say",
"title": "Welcome",
"text": "Greet them warmly and ask what they'd like to order."
},
{
"id": "e5f6a7b8",
"kind": "ask",
"title": "Who it's for",
"text": "",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
]
},
{
"id": "c9d0e1f2",
"kind": "do",
"title": "Send the order to our system",
"text": "",
"action": "webhook"
},
{
"id": "a3b4c5d6",
"kind": "end",
"title": "Thank them",
"text": "Confirm the order and say we'll call to confirm delivery."
}
],
"channels": [],
"updated_at": "2026-11-01T10:00:00+00:00",
"updated_by": "Sam Rivera",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"required": true,
"options": []
},
{
"key": "phone_number",
"label": "Phone number",
"kind": "phone",
"required": true,
"options": []
}
],
"moved_from": []
}Delete a workflow
/agents /{agent_id} /workflows /{workflow_id}Its channels answer normally again. Conversations under way that follow it carry on without it.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
workflow_idstringrequiredThe workflow's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "3f1c2b7a-5d4e-4a9b-8c6d-1e2f3a4b5c6d",
"object": "workflow",
"deleted": true
}Testing
In the portal: Customer Agents › agent › Teach › Testing
Try your agent as you would on the portal's Testing page. Tests are answered and billed like any reply, but they aren't customer conversations: no webhooks are sent and they aren't listed with conversations.
Send a test message
/agents /{agent_id} /testA message from you to your agent. Send the conversation_id it returns to carry on the test.
Messages and read, or full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
messagestringrequiredUp to 2,000 characters.
conversation_idstringCarry on this test.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/test \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "What's your return policy?"
}'{
"id": "2f3a4b5c-6d7e-4f8a-9b0c-1d2e3f4a5b6c",
"object": "test_message",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"conversation_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"reply": "You can return any item within 7 days, unworn and with its tags.",
"usage": {
"charge": "included",
"price_usd": "0",
"input_tokens": 1180,
"output_tokens": 18
}
}Artifacts
In the portal: Customer Agents › agent › Ask agent › + › Artifacts
Photos and documents shared with your agent, and documents it wrote. It can send them to customers; add one to the agent's knowledge to answer from it.
List artifacts
/agents /{agent_id} /artifactsNewest first, up to 200.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Query parameters
kindstringOnly
file(shared documents),image(shared photos) ormade(written by the agent).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "9a1b3c5d-7e9f-4a2b-8c4d-6e8f0a2b4c6d",
"object": "artifact",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"kind": "image",
"title": "size-chart.png",
"mime": "image/png",
"size": 182044,
"created_by": "Sam Rivera",
"created_at": "2026-11-01T10:00:00+00:00"
}
],
"has_more": false
}Share a photo or file
/agents /{agent_id} /artifactsA photo (PNG, JPG, WebP, GIF) or document for your agent, up to about 5 MB.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
namestringrequiredThe file's name, with its extension.
datastringrequiredThe file as base64 (or a data URL).
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "size-chart.png",
"data": "iVBORw0KGgo..."
}'{
"id": "9a1b3c5d-7e9f-4a2b-8c4d-6e8f0a2b4c6d",
"object": "artifact",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"kind": "image",
"title": "size-chart.png",
"mime": "image/png",
"size": 182044,
"created_by": "Sam Rivera",
"created_at": "2026-11-01T10:00:00+00:00"
}Get an artifact
/agents /{agent_id} /artifacts /{artifact_id}One artifact, with the text the agent reads from it.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
artifact_idstringrequiredThe artifact's ID.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "9a1b3c5d-7e9f-4a2b-8c4d-6e8f0a2b4c6d",
"object": "artifact",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"kind": "image",
"title": "size-chart.png",
"mime": "image/png",
"size": 182044,
"created_by": "Sam Rivera",
"created_at": "2026-11-01T10:00:00+00:00",
"text": "Size chart: S 36, M 38, L 40, XL 42 (chest, inches)."
}Download it
/agents /{agent_id} /artifacts /{artifact_id} /fileThe file itself, with its own content type. A document the agent wrote comes as Markdown.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
artifact_idstringrequiredThe artifact's ID.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID/file \
-H "Authorization: Bearer $MARVOXA_API_KEY"(the file)Add it to knowledge
/agents /{agent_id} /artifacts /{artifact_id} /knowledgeAdds what the artifact says to the knowledge base made for this agent, and returns the new document.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
artifact_idstringrequiredThe artifact's ID.
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID/knowledge \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "5e7a9b0c-3d1f-4b6c-8a2e-7f9d1b3c5e70",
"object": "knowledge_document",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"title": "size-chart.png",
"kind": "text",
"words": 64,
"source": null,
"resync": null,
"created_at": "2026-11-01T10:00:00+00:00",
"content": "Size chart: S 36, M 38, L 40, XL 42 (chest, inches)."
}Delete an artifact
/agents /{agent_id} /artifacts /{artifact_id}The agent can't send it any more.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
artifact_idstringrequiredThe artifact's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "9a1b3c5d-7e9f-4a2b-8c4d-6e8f0a2b4c6d",
"object": "artifact",
"deleted": true
}Customer Agents › Reach
Channels
In the portal: Customer Agents › agent › Reach › Channels
Where customers reach your agent: the website widget (chat, and voice calls if it has them), WhatsApp, email and every other channel on your account. Adding a channel needs that service's sign-in or our team, so it's done in the portal. Through the API you can read channels, switch them on and off, choose the apps the agent uses on each, and change how the website chat looks.
List channels
/agents /{agent_id} /channelstype is the channel: website_widget, whatsapp, email, phone or sms. status is setting_up (still being connected) or live. Website chat also has its embed code, websites and look.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/channels \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"id": "2d4f6a8c-0e1b-4d3f-9a5c-7e9b1d3f5a7c",
"object": "channel",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"type": "website_widget",
"name": "Website chat",
"detail": "lumora.studio",
"status": "live",
"enabled": true,
"supports": {
"chat": "yes",
"voice": "yes"
},
"connectors": null,
"billing": "free",
"price_monthly_usd": "0.00",
"paid_until": null,
"chat": true,
"voice": false,
"website": {
"embed": "<script src=\"https://ai-api.marvoxa.com/widget.js\" data-bot=\"ayesha-7k2m\" async></script>",
"websites": [
"lumora.studio"
],
"color": "#6E56CF",
"position": "right",
"style": {
"theme": "light",
"shape": "rounded",
"launcher_text": "Chat with us",
"subtitle": "Usually replies at once",
"starters": [
"Do you ship to Chicago?",
"What sizes do you have?"
]
}
}
}
],
"has_more": false
}Get a channel
/agents /{agent_id} /channels /{channel_id}One channel.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
channel_idstringrequiredThe channel's ID.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/channels/$CHANNEL_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "2d4f6a8c-0e1b-4d3f-9a5c-7e9b1d3f5a7c",
"object": "channel",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"type": "website_widget",
"name": "Website chat",
"detail": "lumora.studio",
"status": "live",
"enabled": true,
"supports": {
"chat": "yes",
"voice": "yes"
},
"connectors": null,
"billing": "free",
"price_monthly_usd": "0.00",
"paid_until": null,
"chat": true,
"voice": false,
"website": {
"embed": "<script src=\"https://ai-api.marvoxa.com/widget.js\" data-bot=\"ayesha-7k2m\" async></script>",
"websites": [
"lumora.studio"
],
"color": "#6E56CF",
"position": "right",
"style": {
"theme": "light",
"shape": "rounded",
"launcher_text": "Chat with us",
"subtitle": "Usually replies at once",
"starters": [
"Do you ship to Chicago?",
"What sizes do you have?"
]
}
}
}Update a channel
/agents /{agent_id} /channels /{channel_id}Send only what changes. chat and website are for website chat. Website voice calls are switched on in voice settings.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
channel_idstringrequiredThe channel's ID.
Body
enabledbooleanThe channel is on.
connectorsstring[]The connectors (their IDs) the agent may use on this channel.
all_connectorsbooleantrue lets it use every connector, including ones added later.
chatbooleanWebsite chat: typed chat on or off.
websiteobjectWebsite chat:
websites(up to 20),color(#6E56CF),position(leftorright) andstyle(theme:light/dark,shape:rounded/soft/square,launcher_text,subtitle, up to 4starters).
curl -X PATCH https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/channels/$CHANNEL_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"website": {
"color": "#0F766E",
"style": {
"starters": [
"Do you ship to Chicago?"
]
}
}
}'{
"id": "2d4f6a8c-0e1b-4d3f-9a5c-7e9b1d3f5a7c",
"object": "channel",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"type": "website_widget",
"name": "Website chat",
"detail": "lumora.studio",
"status": "live",
"enabled": true,
"supports": {
"chat": "yes",
"voice": "yes"
},
"connectors": null,
"billing": "free",
"price_monthly_usd": "0.00",
"paid_until": null,
"chat": true,
"voice": false,
"website": {
"embed": "<script src=\"https://ai-api.marvoxa.com/widget.js\" data-bot=\"ayesha-7k2m\" async></script>",
"websites": [
"lumora.studio"
],
"color": "#0F766E",
"position": "right",
"style": {
"theme": "light",
"shape": "rounded",
"launcher_text": "Chat with us",
"subtitle": "Usually replies at once",
"starters": [
"Do you ship to Chicago?"
]
}
}
}Chat settings
In the portal: Customer Agents › agent › Reach › Chat
How your agent behaves in chat: its job, your instructions, and when it brings in a person from your team.
Get chat settings
/agents /{agent_id} /chat-settingsThe agent's chat settings.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/chat-settings \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "chat_settings",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"job": {
"jobs": [
"answer",
"sell",
"orders"
],
"tone": "friendly",
"person": "When they want to return an order."
},
"instructions": "Prices are in US dollars. Never promise same-day delivery.",
"thinking": false,
"human_help": {
"enabled": true,
"when": "asked",
"message": ""
},
"handoff_contact": "Call or text (718) 555-0136"
}Update chat settings
/agents /{agent_id} /chat-settingsSend only what changes.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
jobobjectjobs: any ofanswer,sell,orders,bookings,support,explain.tone:friendly,professional,shortordetailed.person: when to bring in your team, in your words.instructionsstringAnything it should always know or do, up to 20,000 characters.
thinkingbooleanThink before answering: better on tricky questions, a little slower.
human_helpobjectenabled;when:asked(when they ask for a person) orstuck(also when it can't help);message: what it says when it hands over.handoff_contactstringWho customers are pointed to when they want a person (a number or email), up to 200 characters.
curl -X PATCH https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/chat-settings \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"human_help": {
"enabled": true,
"when": "stuck"
}
}'{
"object": "chat_settings",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"job": {
"jobs": [
"answer",
"sell",
"orders"
],
"tone": "friendly",
"person": "When they want to return an order."
},
"instructions": "Prices are in US dollars. Never promise same-day delivery.",
"thinking": false,
"human_help": {
"enabled": true,
"when": "stuck",
"message": ""
},
"handoff_contact": "Call or text (718) 555-0136"
}Voice settings
In the portal: Customer Agents › agent › Reach › Voice
Voice calls from your website chat, and voice replies to WhatsApp voice notes. Calls need a package with voice minutes on your account (plan_live).
Get voice settings
/agents /{agent_id} /voice-settingsThe agent's voice, its greeting, and the words it should hear right.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/voice-settings \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "voice_settings",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"enabled": true,
"voice": "female",
"greeting": "Hi! Lumora Studio, Ava speaking.",
"vocabulary": [
"linen",
"merino",
"Lumora Studio"
],
"about": "",
"whatsapp_replies": false,
"plan_live": true,
"available": true
}Update voice settings
/agents /{agent_id} /voice-settingsSend only what changes. Switching calls on without voice minutes in your package returns 409.
Full access
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Body
enabledbooleanVoice calls from the website chat.
voicestringfemale,male, or a voice'sidfrom List voices.greetingstringWhat it says when it picks up, up to 300 characters.
vocabularystring[]Names and words callers may say (products, brands, places), so it hears them right. Up to 300.
aboutstringOne line on who calls and why (
Shoppers calling a clothes store), up to 200 characters.whatsapp_repliesbooleanAnswer a WhatsApp voice note with a voice note.
curl -X PATCH https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/voice-settings \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vocabulary": [
"linen",
"merino",
"Lumora Studio"
]
}'{
"object": "voice_settings",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"enabled": true,
"voice": "female",
"greeting": "Hi! Lumora Studio, Ava speaking.",
"vocabulary": [
"linen",
"merino",
"Lumora Studio"
],
"about": "",
"whatsapp_replies": false,
"plan_live": true,
"available": true
}Suggest vocabulary
/agents /{agent_id} /voice-settings /vocabulary-suggestionsNames and terms from the agent's knowledge that aren't in its vocabulary yet.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/voice-settings/vocabulary-suggestions \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "vocabulary_suggestions",
"suggestions": [
"Wythe Ave",
"stonewashed",
"cardigan"
]
}List voices
/voicesThe voices your agents can speak with: Urdu, English (Pakistani, American and British) and Arabic voices, each under a Marvoxa name. Every voice costs the same per minute. Listen with preview_url where there is one; best_for holds use keys (sales, support, assistant, receptionist, bookings, announcements). Set one on an agent with its id in voice-settings.
Any key
curl https://ai-api.marvoxa.com/v1/voices \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"object": "voice",
"id": "EXAVITQu4vr4xnSDxMaL",
"name": "Ayesha",
"description": "Warm Pakistani voice for Urdu and English calls.",
"gender": "female",
"age": "young",
"accent": "pakistani",
"languages": [
"Urdu (Pakistani)",
"English (Pakistani)"
],
"urdu": true,
"best_for": [
"support",
"receptionist"
],
"preview_url": null
}
],
"has_more": false
}Customer Agents › Usage
Usage
In the portal: Customer Agents › Usage & billing
One agent's month: its replies and voice minutes, its extras by kind, and what it cost. The account's totals by module are in Billing & usage.
Get its usage
/agents /{agent_id} /usageReplies, extra replies, conversations, voice minutes and spend, by day and by channel. extras_by_kind is what was charged beyond the package: customers' extra replies, voice minutes, and your team's questions to this agent (Ask agent). cost is what the agent cost: its share of the packages (by replies and minutes), its extras, its channels and connectors, the total, and an estimate_usd for the month at the pace so far.
Any key
Path parameters
agent_idstringrequiredYour agent's ID (in the portal: the agent's address).
Query parameters
monthstringYYYY-MM(month01to12). This month if left out.
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/usage \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "usage",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"month": "2026-11",
"replies": 1312,
"extra_replies": 0,
"conversations": 284,
"spend_usd": "0.00",
"input_tokens": 1622030,
"output_tokens": 58210,
"calls": {
"count": 41,
"seconds": 5310,
"charge_usd": "0.00",
"avg_response_ms": 820
},
"daily": [
{
"date": "2026-11-01",
"replies": 96,
"extra_replies": 0,
"spend_usd": "0.00"
}
],
"by_channel": [
{
"channel": "web",
"replies": 702,
"spend_usd": "0.00"
},
{
"channel": "whatsapp",
"replies": 492,
"spend_usd": "0.00"
},
{
"channel": "api",
"replies": 118,
"spend_usd": "0.00"
}
],
"voice_minutes": 88.5,
"extras_by_kind": {
"replies_usd": "1.20",
"voice_usd": "0.00",
"team_usd": "0.35"
},
"cost": {
"plan_share_usd": "7.20",
"extras_usd": "1.55",
"channels_usd": "0.00",
"total_usd": "8.75",
"estimate_usd": "9.20",
"per_conversation_usd": "0.0308",
"per_reply_usd": "0.0067"
}
}Webhooks
Webhook endpoints
In the portal: Developers › Webhooks
Addresses on your server that get events as they happen (see Webhooks below). Each one can get events from every agent, or only the agents you choose. Needs a key that reaches this module.
List webhooks
/account /webhooksYour webhook endpoints, and every event type you can choose (events).
Any keyKey that reaches this module
curl https://ai-api.marvoxa.com/v1/account/webhooks \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"object": "webhook",
"id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
"url": "https://lumora.studio/hooks/marvoxa",
"description": "Orders into our CRM",
"events": [
"message.replied",
"handoff.requested",
"workflow.webhook"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"enabled": true,
"disabled_reason": null,
"failures": 0,
"created_at": "2026-11-01T10:00:00+00:00",
"created_by": "Sam Rivera"
}
],
"has_more": false,
"events": [
{
"type": "message.replied",
"description": "The agent replied to a customer."
}
]
}Create a webhook
/account /webhooksA new endpoint. Its signing secret (whsec_...) is in this answer only: keep it to verify signatures.
Full accessKey that reaches this module
Body
urlstringrequiredAn https address on your server.
eventsstring[]requiredThe event types to send, at least one.
descriptionstringWhat it's for, up to 200 characters.
agent_idsstring[]Only events from these agents. Empty or left out: every agent, including ones you add later.
curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://lumora.studio/hooks/marvoxa",
"events": [
"message.replied",
"handoff.requested"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
]
}'{
"object": "webhook",
"id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
"url": "https://lumora.studio/hooks/marvoxa",
"description": "Orders into our CRM",
"events": [
"message.replied",
"handoff.requested",
"workflow.webhook"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"enabled": true,
"disabled_reason": null,
"failures": 0,
"created_at": "2026-11-01T10:00:00+00:00",
"created_by": "Sam Rivera",
"secret": "whsec_9f8e7d6c5b4a..."
}Get a webhook
/account /webhooks /{webhook_id}One endpoint. failures counts failed deliveries in a row; at 50 it's switched off (disabled_reason).
Any keyKey that reaches this module
Path parameters
webhook_idstringrequiredThe webhook's ID.
curl https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "webhook",
"id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
"url": "https://lumora.studio/hooks/marvoxa",
"description": "Orders into our CRM",
"events": [
"message.replied",
"handoff.requested",
"workflow.webhook"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
}
],
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"enabled": true,
"disabled_reason": null,
"failures": 0,
"created_at": "2026-11-01T10:00:00+00:00",
"created_by": "Sam Rivera"
}Update a webhook
/account /webhooks /{webhook_id}Send only what changes. Switching it back on clears its failures.
Full accessKey that reaches this module
Path parameters
webhook_idstringrequiredThe webhook's ID.
Body
urlstringAn https address.
eventsstring[]The event types to send.
descriptionstringUp to 200 characters.
enabledbooleanOn or off.
agent_idsstring[]Only these agents; empty for every agent.
curl -X PATCH https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"8c2d4e6f-1a3b-4c5d-9e7f-2b4d6f8a0c1e"
]
}'{
"object": "webhook",
"id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
"url": "https://lumora.studio/hooks/marvoxa",
"description": "Orders into our CRM",
"events": [
"message.replied",
"handoff.requested",
"workflow.webhook"
],
"agent_ids": [
"3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"8c2d4e6f-1a3b-4c5d-9e7f-2b4d6f8a0c1e"
],
"agents": [
{
"id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"name": "Ava"
},
{
"id": "8c2d4e6f-1a3b-4c5d-9e7f-2b4d6f8a0c1e",
"name": "Bilal"
}
],
"agent_id": null,
"enabled": true,
"disabled_reason": null,
"failures": 0,
"created_at": "2026-11-01T10:00:00+00:00",
"created_by": "Sam Rivera"
}Delete a webhook
/account /webhooks /{webhook_id}Events stop going to it at once.
Full accessKey that reaches this module
Path parameters
webhook_idstringrequiredThe webhook's ID.
curl -X DELETE https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
"object": "webhook",
"deleted": true
}Roll its secret
/account /webhooks /{webhook_id} /secretA new signing secret. The old one stops working at once.
Full accessKey that reaches this module
Path parameters
webhook_idstringrequiredThe webhook's ID.
curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/secret \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "webhook_secret",
"webhook_id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
"secret": "whsec_1a2b3c4d5e6f..."
}Send a test event
/account /webhooks /{webhook_id} /testSends a ping event now, and says how your server answered.
Full accessKey that reaches this module
Path parameters
webhook_idstringrequiredThe webhook's ID.
curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/test \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "webhook_delivery",
"id": "0b2d4f6a-8c0e-4b2d-9f6a-8c0e2b4d6f8a",
"event_id": "evt_4b1f0c9e2d7a6b3c8e5f1a2d",
"event_type": "ping",
"status": "delivered",
"attempts": 1,
"next_attempt_at": null,
"response_status": 200,
"response_body": "ok",
"error": null,
"duration_ms": 182,
"created_at": "2026-11-01T10:00:00+00:00",
"delivered_at": "2026-11-01T10:00:00+00:00",
"payload": {
"type": "ping"
}
}List deliveries
/account /webhooks /{webhook_id} /deliveriesThe last 50 deliveries to this endpoint, newest first, with what your server answered.
Any keyKey that reaches this module
Path parameters
webhook_idstringrequiredThe webhook's ID.
Query parameters
statusstringOnly
pending,deliveredorfailed.
curl https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/deliveries \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "list",
"data": [
{
"object": "webhook_delivery",
"id": "0b2d4f6a-8c0e-4b2d-9f6a-8c0e2b4d6f8a",
"event_id": "evt_4b1f0c9e2d7a6b3c8e5f1a2d",
"event_type": "message.replied",
"status": "delivered",
"attempts": 1,
"next_attempt_at": null,
"response_status": 200,
"response_body": "ok",
"error": null,
"duration_ms": 182,
"created_at": "2026-11-01T10:00:00+00:00",
"delivered_at": "2026-11-01T10:00:00+00:00",
"payload": {
"id": "evt_4b1f0c9e2d7a6b3c8e5f1a2d",
"type": "message.replied"
}
}
],
"has_more": false
}Send a delivery again
/account /webhooks /deliveries /{delivery_id} /retrySends it again now, whatever happened to it before.
Full accessKey that reaches this module
Path parameters
delivery_idstringrequiredThe delivery's ID.
curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/deliveries/$DELIVERY_ID/retry \
-H "Authorization: Bearer $MARVOXA_API_KEY"{
"object": "webhook_delivery",
"id": "0b2d4f6a-8c0e-4b2d-9f6a-8c0e2b4d6f8a",
"event_id": "evt_4b1f0c9e2d7a6b3c8e5f1a2d",
"event_type": "message.replied",
"status": "delivered",
"attempts": 2,
"next_attempt_at": null,
"response_status": 200,
"response_body": "ok",
"error": null,
"duration_ms": 182,
"created_at": "2026-11-01T10:00:00+00:00",
"delivered_at": "2026-11-01T10:00:00+00:00",
"payload": {
"id": "evt_4b1f0c9e2d7a6b3c8e5f1a2d",
"type": "message.replied"
}
}Webhooks
Webhooks tell your systems what happens in your modules as it happens: in Customer Agents a new conversation, a reply or a customer asking for a person, in Knowledge a page that changed, in Connectors a sign-in that ran out. Add an https address on the console's API and webhooks page (or with Create a webhook), pick its modules and their events (and, for Customer Agents, which agents), and keep its signing secret.
We POST each event as JSON. Answer with any 2xx status within 10 seconds. Anything else is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours. An address that fails 50 times in a row is switched off; switch it back on in the portal. The portal shows every delivery for 30 days, with what your server answered, and can send any of them again.
Events can arrive more than once and out of order. Use the event's id to skip ones you've seen, and created_at to order them. Events from your own Ask agent and portal tests aren't sent.
{
"id": "evt_4b1f0c9e2d7a6b3c8e5f1a2d",
"object": "event",
"type": "message.replied",
"created_at": "2026-11-01T10:00:02+00:00",
"data": {
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"conversation": {
"id": "a1c9e7d2-4f3b-4e8a-b6d5-2c7f9e1a3b4d",
"agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
"channel": "whatsapp",
"user": null,
"status": "open",
"human": null,
"workflow_id": null,
"details": {}
},
"message": {
"id": "6d0f3c2a-91b7-4a5e-8f4d-3b2c1a0e9d8f",
"role": "assistant",
"text": "Yes! We ship to Chicago in 2-4 business days.",
"via": "chat",
"created_at": "2026-11-01T10:00:02+00:00"
},
"usage": {
"charge": "included",
"price_usd": "0"
}
}
}Event types
Every event has id, type, created_at and data. data.conversation is in every conversation event; data.message is in message.* events; message.held has data.reason (no_plan, unpaid, trial_limit, package_used or extra_limit).
conversation.createdModuleCustomer Agents
WhenA customer started a new conversation, on any channel.
message.receivedModuleCustomer Agents
WhenA customer sent a message.
message.repliedModuleCustomer Agents
WhenYour agent replied to a customer (with how it was paid).
message.heldModuleCustomer Agents
WhenA message wasn't answered by AI: no package, or this month's replies are used.
handoff.requestedModuleCustomer Agents
WhenA customer asked for a person from your team.
conversation.endedModuleCustomer Agents
WhenYour agent ended a conversation: a workflow's End step, or a call it said goodbye on. The conversation's
statusis thenclosed, until the customer writes again.details.savedModuleCustomer Agents
WhenYour agent saved details a workflow asks for (
data.saved), such as a name or phone number.workflow.webhookModuleCustomer Agents
WhenA conversation reached a workflow's Send to webhook step:
data.workflow,data.stepand every detail collected so far indata.details.lead.createdModuleCustomer Agents
WhenA new lead (
data.lead): a workflow saved a customer's details, or they typed a phone number or email in a conversation. Once per conversation.knowledge.syncedModuleKnowledge
WhenA web page or website in a knowledge base was read again and had changed (
data.doc_id,data.title,data.source).knowledge.sync_failedModuleKnowledge
WhenA web page or website in a knowledge base couldn't be read again (
data.errorsays why).connector.needs_sign_inModuleConnectors
WhenA connector's sign-in ran out (
data.connector_id,data.label): sign in again in the console so agents can use it.pingModuleAny
WhenA test event, sent from the console.
Verifying signatures
Each request has a Marvoxa-Signature header: t=<unix time>,v1=<signature>. The signature is the hex HMAC-SHA256 of the time, a dot and the raw body, with your endpoint's secret (whsec_...) as the key. Check it, and reject requests more than 5 minutes old, so no one else can send you events.
Requests also carry Marvoxa-Event (the type), Marvoxa-Event-Id and Marvoxa-Delivery (this attempt's ID).
import crypto from "node:crypto";
// Use the raw request body, before JSON parsing.
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 minutes
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 ?? "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", 0))
if abs(time.time() - t) > 300: # 5 minutes
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))