Skip to content

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.

Base URL https://ai-api.marvoxa.com/v1JSON over HTTPSBearer key authSigned webhooks
On 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.

Base URL
https://ai-api.marvoxa.com/v1

Quickstart

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.

Your first message
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.

Map
/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, voices

Authentication 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.

  • read

    Read everything the key reaches: agents, settings, knowledge, conversations, usage, billing.

  • messages

    Also talk to agents as a customer, and send test messages. Keys made before access levels existed have this.

  • full

    Also change things: agents and their settings, knowledge bases, connectors, artifacts, channels, workflows, conversations (take over and reply), team members, account settings and webhooks.

Header
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.

  • trial

    From your free trial.

  • included

    From this month's package.

  • extra

    Beyond 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).

The next page
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.

  • 401

    typeauthentication_error

    WhenNo key, or a wrong or revoked one.

  • 403

    typepermission_denied

    WhenThe account is paused, the key's access level doesn't allow it, or the key doesn't reach this module.

  • 404

    typenot_found

    WhenThe agent, conversation or item isn't one this key can reach.

  • 409

    typeconflict

    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.

  • 422

    typeinvalid_request

    WhenA field is missing, too long or not one of the choices.

  • 429

    typerate_limit_exceeded

    WhenToo many requests; wait a little and try again.

  • 502

    typeagent_error

    WhenThe AI couldn't answer this time; try again.

Error
{
  "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

GET/account

Your 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"
Response
{
  "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

GET/key

Its 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"
Response
{
  "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

GET/usage

Your 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"
Response
{
  "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

GET/account/settings

Your 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"
Response
{
  "object": "account_settings",
  "business_name": "Lumora Studio",
  "owner_name": "Sam Rivera",
  "owner_phone": "(718) 555-0136",
  "industry": "fashion"
}

Update settings

PATCH/account/settings

Send only what changes.

Full accessKey that reaches this module

Body

  • business_namestring

    Up to 160 characters.

  • owner_namestring

    Up to 120 characters.

  • owner_phonestring

    Digits, spaces, +, - and brackets.

  • industrystring

    Up 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"
  }'
Response
{
  "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

GET/account/team

Everyone 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"
Response
{
  "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

POST/account/team

Adds 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

  • namestringrequired

    Up to 120 characters.

  • emailstringrequired

    Their 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"
  }'
Response
{
  "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

PATCH/account/team/{user_id}

active: false stops them signing in until restored.

Full accessKey that reaches this module

Path parameters

  • user_idstringrequired

    The team member's ID.

Body

  • activeboolean

    Can 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
  }'
Response
{
  "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

DELETE/account/team/{user_id}

They can't sign in any more.

Full accessKey that reaches this module

Path parameters

  • user_idstringrequired

    The team member's ID.

curl -X DELETE https://ai-api.marvoxa.com/v1/account/team/$USER_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/account/billing

This 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"
Response
{
  "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

GET/account/usage

A 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

  • monthstring

    YYYY-MM (month 01 to 12). This month if left out.

curl https://ai-api.marvoxa.com/v1/account/usage \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/account/billing/invoices

Your 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"
Response
{
  "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

GET/account/billing/invoices/{invoice_id}

One invoice with its lines and exchange rate.

Any keyKey that reaches this module

Path parameters

  • invoice_idstringrequired

    The invoice's ID.

curl https://ai-api.marvoxa.com/v1/account/billing/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/account/billing/transactions

A 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

  • monthstring

    YYYY-MM (month 01 to 12). This month if left out.

curl https://ai-api.marvoxa.com/v1/account/billing/transactions \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/connectors

The 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"
Response
{
  "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

GET/connectors/apps

The 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"
Response
{
  "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

POST/connectors

Starts 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

  • appstringrequired

    The app's slug, from List apps.

  • understoodboolean

    You accept that a private app lets your agents read its conversations. Needed for those apps.

  • agent_idstring

    Attach 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"
  }'
Response
{
  "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

GET/connectors/{connection_id}

One connected app, and the agents it's attached to.

Any keyKey that reaches this module

Path parameters

  • connection_idstringrequired

    The connection's ID.

curl https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/connectors/{connection_id}/check

Asks 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_idstringrequired

    The connection's ID.

curl -X POST https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID/check \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

DELETE/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_idstringrequired

    The connection's ID.

curl -X DELETE https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/connectors/custom

Saves 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

  • kindstringrequired

    api or mcp.

  • namestringrequired

    What you and your agents call it (1 to 120 characters).

  • base_urlstring

    An API's address, like https://api.yourcompany.com/v1. Needs https.

  • urlstring

    An MCP server's address, like https://mcp.yourcompany.com/mcp. Needs https.

  • authobjectrequired

    How it signs in: {type}, with type one of none, api_key (add in: header or query, and name, like X-API-Key), bearer, basic or oauth_client (add token_url and an optional scope) for an API; none, bearer or header (add name) for an MCP server.

  • secretsobject

    The keys it needs, each a string: api_key, token, username and password, client_id and client_secret, or header (the custom header's value).

  • headersarray

    An 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_…"
    }
  }'
Response
{
  "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

GET/connectors/custom

Your 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"
Response
{
  "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

GET/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_idstringrequired

    The 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"
Response
{
  "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

PATCH/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_idstringrequired

    The custom connector's ID (the same as its connection's id).

Body

  • namestring

    Its name.

  • base_urlstring

    An API's address.

  • urlstring

    An MCP server's address.

  • authobject

    How it signs in, as when connecting.

  • secretsobject

    New keys, as when connecting.

  • headersarray

    An API's extra headers: the whole list.

  • timeout_sinteger

    How long to wait for an answer, 2 to 30 seconds (a voice call waits 5 at most).

  • calls_per_minuteinteger

    How 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
  }'
Response
{
  "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

DELETE/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_idstringrequired

    The 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"
Response
{
  "id": "b2d4f6a8-0c1e-4b3d-9f5a-7c9e1b3d5f7a",
  "object": "custom_connector",
  "deleted": true,
  "refunded_usd": "0.000000"
}

Test the connection

POST/connectors/custom/{custom_id}/check

Calls 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_idstringrequired

    The 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"
Response
{
  "object": "connector_check",
  "ok": true,
  "status": 200,
  "ms": 212,
  "message": "Connected. The API answered in 212 ms."
}

List tools

GET/connectors/custom/{custom_id}/tools

Its 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_idstringrequired

    The 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"
Response
{
  "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

POST/connectors/custom/{custom_id}/tools

Adds 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_idstringrequired

    The custom connector's ID (the same as its connection's id).

Body

  • toolsarrayrequired

    The tools to add. Each is {name, description, method, path, inputs, fixed, fields, results_path, max_results, changes, enabled}. name is what people call it, and description says when agents should use it, in plain words. method is GET, POST, PUT, PATCH or DELETE, and path starts with / (each {name} in it needs a path input). inputs are what the agent fills in: {name, in, type, required, description, enum, example, wire}, with in one of query, path, body or header and type one of string, number, integer, boolean or array (a list of strings); a dotted body name (address.city) sends a nested value. An input's name is up to 64 letters, digits, _, - and .; when your API uses another name, like page[size] or $filter, put that in wire and it's sent instead (null or left out sends name). A tool you get back has wire only on the inputs that use one. fixed values ({name, in, value}) are always sent, and the agent never sees them. fields are the dotted paths of the reply agents see (empty for all of it), results_path is where the list sits in the reply (null to find it), and max_results is 1 to 50 (default 10). changes (default: true for anything but GET) makes the agent ask the customer to confirm before it runs. A key (the tool's name for the AI, lower case and underscores) is made from name when 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"
          }
        ]
      }
    ]
  }'
Response
{
  "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

GET/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_idstringrequired

    The custom connector's ID (the same as its connection's id).

  • tool_idstringrequired

    The tool's ID.

curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools/$TOOL_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

PATCH/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_idstringrequired

    The custom connector's ID (the same as its connection's id).

  • tool_idstringrequired

    The tool's ID.

Body

  • enabledboolean

    Agents may use it.

  • changesboolean

    It creates, changes or deletes something: the customer confirms before it runs.

  • namestring

    Its name.

  • descriptionstring

    When agents should use it.

  • methodstring

    The request's method (API tools).

  • pathstring

    The request's path (API tools).

  • inputsarray

    What the agent fills in: the whole list (API tools).

  • fixedarray

    Values always sent: the whole list (API tools).

  • fieldsarray

    The reply's fields agents see; empty for all (API tools).

  • results_pathstring

    Where the list sits in the reply (API tools).

  • max_resultsinteger

    Results 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"
    ]
  }'
Response
{
  "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

DELETE/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_idstringrequired

    The custom connector's ID (the same as its connection's id).

  • tool_idstringrequired

    The 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"
Response
{
  "id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
  "object": "connector_tool",
  "deleted": true
}

Test a tool

POST/connectors/custom/{custom_id}/tools/{tool_id}/test

Runs 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_idstringrequired

    The custom connector's ID (the same as its connection's id).

  • tool_idstringrequired

    The tool's ID.

Body

  • argumentsobject

    The 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"
    }
  }'
Response
{
  "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

GET/connectors/custom/{custom_id}/activity

Its 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_idstringrequired

    The custom connector's ID (the same as its connection's id).

Query parameters

  • limitinteger

    How many, 1 to 200. Default 50.

  • beforestring

    Calls before this time (an earlier answer's last at), for the next page.

  • statusstring

    Only ok, failed, waiting, confirmed or blocked calls. Name several with commas.

  • toolstring

    Only 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"
Response
{
  "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

POST/connectors/import

Reads 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

  • urlstring

    A link to the description, like https://api.yourcompany.com/openapi.json.

  • textstring

    The description itself.

  • fileobject

    A file: {name, data}, with data in 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"
  }'
Response
{
  "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

GET/knowledge-bases

Every 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"
Response
{
  "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

POST/knowledge-bases

A new, empty knowledge base. Up to 50 on an account.

Full accessKey that reaches this module

Body

  • namestringrequired

    Up to 120 characters.

  • descriptionstring

    What'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"
    ]
  }'
Response
{
  "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

GET/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_idstringrequired

    The knowledge base's ID.

curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

PATCH/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_idstringrequired

    The knowledge base's ID.

Body

  • namestring

    Up to 120 characters.

  • descriptionstring

    Up 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"
    ]
  }'
Response
{
  "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

DELETE/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_idstringrequired

    The knowledge base's ID.

curl -X DELETE https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/knowledge-bases/{kb_id}/documents

Its 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_idstringrequired

    The knowledge base's ID.

curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/knowledge-bases/{kb_id}/documents

A document from your own text.

Full accessKey that reaches this module

Path parameters

  • kb_idstringrequired

    The knowledge base's ID.

Body

  • titlestringrequired

    Up to 200 characters.

  • contentstringrequired

    The text, up to 100,000 characters.

  • kindstring

    What it is, in your words (Menu, Delivery policy). Default text.

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"
  }'
Response
{
  "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

POST/knowledge-bases/{kb_id}/documents/import

Reads 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_idstringrequired

    The knowledge base's ID.

Body

  • urlstringrequired

    The page's address.

  • kindstring

    What it is, in your words (Menu, Delivery policy). Default text.

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"
  }'
Response
{
  "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

POST/knowledge-bases/{kb_id}/documents/upload

Reads 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_idstringrequired

    The knowledge base's ID.

Body

  • namestringrequired

    The file's name, with its extension.

  • datastringrequired

    The file as base64 (or a data URL).

  • kindstring

    What it is, in your words (Menu, Delivery policy). Default text.

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="
  }'
Response
{
  "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

GET/knowledge-bases/{kb_id}/documents/{doc_id}

One document, with its text.

Any keyKey that reaches this module

Path parameters

  • kb_idstringrequired

    The knowledge base's ID.

  • doc_idstringrequired

    The document's ID.

curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/$DOC_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

PATCH/knowledge-bases/{kb_id}/documents/{doc_id}

Send only what changes.

Full accessKey that reaches this module

Path parameters

  • kb_idstringrequired

    The knowledge base's ID.

  • doc_idstringrequired

    The document's ID.

Body

  • titlestring

    Up to 200 characters.

  • contentstring

    Up to 100,000 characters.

  • kindstring

    What 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."
  }'
Response
{
  "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

POST/knowledge-bases/{kb_id}/documents/{doc_id}/resync

Reads 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_idstringrequired

    The knowledge base's ID.

  • doc_idstringrequired

    The 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"
Response
{
  "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

DELETE/knowledge-bases/{kb_id}/documents/{doc_id}

Agents stop using it at once.

Full accessKey that reaches this module

Path parameters

  • kb_idstringrequired

    The knowledge base's ID.

  • doc_idstringrequired

    The 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"
Response
{
  "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

POST/knowledge-bases/{kb_id}/search

The 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_idstringrequired

    The knowledge base's ID.

Body

  • questionstringrequired

    What 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?"
  }'
Response
{
  "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

POST/knowledge-bases/{kb_id}/tests

A 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_idstringrequired

    The knowledge base's ID.

Body

  • questionstringrequired

    Up to 300 characters.

  • expectstringrequired

    A 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"
  }'
Response
{
  "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

POST/knowledge-bases/{kb_id}/tests/run

Runs every test question again now.

Full accessKey that reaches this module

Path parameters

  • kb_idstringrequired

    The 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"
Response
{
  "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

DELETE/knowledge-bases/{kb_id}/tests/{test_id}

It stops running.

Full accessKey that reaches this module

Path parameters

  • kb_idstringrequired

    The knowledge base's ID.

  • test_idstringrequired

    The 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"
Response
{
  "id": "cfecbcba5166",
  "object": "knowledge_test",
  "deleted": true
}

Find documents that disagree

POST/knowledge-bases/{kb_id}/check

Marvoxa 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_idstringrequired

    The knowledge base's ID.

curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/check \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/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_idstringrequired

    The knowledge base's ID.

  • conflict_idstringrequired

    The disagreement's id.

Body

  • chosenstring | nullrequired

    a or b, 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"
  }'
Response
{
  "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

GET/knowledge-gaps

Most 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"
Response
{
  "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

POST/knowledge-gaps/scan

Marvoxa 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"
Response
{
  "object": "knowledge_gap_scan",
  "added": 2,
  "price_usd": "0.000910"
}

Update a gap

PATCH/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_idstringrequired

    The gap's ID.

Body

  • questionstring

    Up to 300 characters.

  • answerstring

    Up to 2,000 characters.

  • knowledge_base_idstring

    The 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."
  }'
Response
{
  "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

POST/knowledge-gaps/{gap_id}/add

Adds 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_idstringrequired

    The gap's ID.

curl -X POST https://ai-api.marvoxa.com/v1/knowledge-gaps/$GAP_ID/add \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/knowledge-gaps/{gap_id}/dismiss

It isn't listed again.

Full accessKey that reaches this module

Path parameters

  • gap_idstringrequired

    The gap's ID.

curl -X POST https://ai-api.marvoxa.com/v1/knowledge-gaps/$GAP_ID/dismiss \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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.

List agents

GET/agents

The agents this key can reach, oldest first.

Any key

curl https://ai-api.marvoxa.com/v1/agents \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/agents

A 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

  • namestringrequired

    Its name, up to 80 characters.

  • languagestring

    auto (answers in the customer's language), en, ur or roman-ur. Default auto.

  • greetingstring

    Its first message, up to 300 characters.

  • instructionsstring

    Anything 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?"
  }'
Response
{
  "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

GET/agents/{agent_id}

One agent. status is live, off (paused) or draft (still being set up).

Any key

Path parameters

  • agent_idstringrequired

    Your 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"
Response
{
  "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

PATCH/agents/{agent_id}

The agent's Settings page. Send only what changes. enabled: false pauses it on every channel.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • namestring

    Up to 80 characters.

  • languagestring

    auto, en, ur or roman-ur.

  • greetingstring

    Up to 300 characters.

  • enabledboolean

    Answering 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?"
  }'
Response
{
  "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

PUT/agents/{agent_id}/avatar

The 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • imagestring | nullrequired

    data: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
  }'
Response
{
  "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

DELETE/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Query parameters

  • confirmstring

    The 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"
Response
{
  "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

POST/agents/{agent_id}/messages

Sends 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • messagestringrequired

    What the customer said. Up to 2,000 characters.

  • conversation_idstring

    Carry on this conversation. Leave it out to start a new one.

  • userstring

    Your own ID for the person, up to 100 characters.

  • streamboolean

    Stream the reply as server-sent events: conversation, then delta pieces of text, then done with the whole message (or error).

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"
  }'
Response
{
  "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

GET/agents/{agent_id}/conversations

Newest first, on every channel: website chat (web), website voice calls (call), WhatsApp and the API.

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Query parameters

  • channelstring

    Only one channel: web, whatsapp, call or api.

  • userstring

    Only this person's API conversations.

  • limitinteger

    How many, 1 to 100. Default 20.

  • beforetimestamp

    For 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"
Response
{
  "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

GET/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • conversation_idstringrequired

    The conversation's ID.

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/agents/{agent_id}/conversations/{conversation_id}/messages

A page of a conversation, oldest first: the customer (user), your agent (assistant) and your team (staff).

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • conversation_idstringrequired

    The conversation's ID.

Query parameters

  • limitinteger

    How many, 1 to 100. Default 50.

  • beforestring

    For 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"
Response
{
  "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

POST/agents/{agent_id}/conversations/{conversation_id}/take

Your 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • conversation_idstringrequired

    The 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"
Response
{
  "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

POST/agents/{agent_id}/conversations/{conversation_id}/reply

Sends 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • conversation_idstringrequired

    The conversation's ID.

Body

  • textstringrequired

    Up 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."
  }'
Response
{
  "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

POST/agents/{agent_id}/conversations/{conversation_id}/release

Hands the conversation back to the agent.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • conversation_idstringrequired

    The 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"
Response
{
  "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

GET/agents/{agent_id}/leads

Newest 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Query parameters

  • statusstring

    Only one status: new, contacted, won or lost.

  • sourcestring

    workflow or chat.

  • channelstring

    Only one channel: web, call, whatsapp or api.

  • qstring

    Search names, phone numbers, emails, what they asked, details and notes.

  • sincedate

    From this day (YYYY-MM-DD, Pakistan time), included.

  • untildate

    Up to this day, included.

  • limitinteger

    How many, 1 to 100. Default 20.

  • beforetimestamp

    For 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"
Response
{
  "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

GET/agents/{agent_id}/leads/settings

capture: 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_idstringrequired

    Your 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"
Response
{
  "object": "lead_settings",
  "agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
  "capture": true
}

Update lead settings

PATCH/agents/{agent_id}/leads/settings

Turns picking up leads from conversations on or off.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • capturebooleanrequired

    On 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
  }'
Response
{
  "object": "lead_settings",
  "agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
  "capture": false
}

Get a lead

GET/agents/{agent_id}/leads/{lead_id}

One lead.

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • lead_idstringrequired

    The lead's ID.

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/$LEAD_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

PATCH/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • lead_idstringrequired

    The lead's ID.

Body

  • statusstring

    new, contacted, won or lost.

  • notestring

    Your team's note, up to 4,000 characters.

  • namestring

    Up to 160 characters.

  • phonestring

    Up to 40 characters.

  • emailstring

    Up 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."
  }'
Response
{
  "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

DELETE/agents/{agent_id}/leads/{lead_id}

Removes the lead. The conversation it came from stays.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • lead_idstringrequired

    The lead's ID.

curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/$LEAD_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/agents/{agent_id}/knowledge-bases

In the order they were attached. words is what the agent reads from all of them.

Any key

Path parameters

  • agent_idstringrequired

    Your 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"
Response
{
  "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

POST/agents/{agent_id}/knowledge-bases

The 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • knowledge_base_idstringrequired

    One 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"
  }'
Response
{
  "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

PUT/agents/{agent_id}/knowledge-bases

Exactly these knowledge bases, in this order; any others are detached.

Full accessKey that reaches this module

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • knowledge_base_idsstring[]required

    Up 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"
    ]
  }'
Response
{
  "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

DELETE/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • kb_idstringrequired

    The 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"
Response
{
  "id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
  "object": "knowledge_base",
  "agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
  "detached": true
}

Let Marvoxa choose

POST/agents/{agent_id}/knowledge-bases/choose

Marvoxa 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_idstringrequired

    Your 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"
Response
{
  "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

GET/agents/{agent_id}/connectors

The 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_idstringrequired

    Your 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"
Response
{
  "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

POST/agents/{agent_id}/connectors

Attaches 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • connection_idstringrequired

    A 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"
  }'
Response
{
  "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

GET/agents/{agent_id}/connectors/{connector_id}

One attached app and what the agent may do with it.

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • connector_idstringrequired

    The connector's ID.

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors/$CONNECTOR_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

PATCH/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • connector_idstringrequired

    The connector's ID.

Body

  • enabledboolean

    The agent may use the app.

  • actionsobject

    {"ACTION_KEY": false}: switch actions on (true) or off (false), by their key.

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
    }
  }'
Response
{
  "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

DELETE/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • connector_idstringrequired

    The connector's ID.

curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors/$CONNECTOR_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/agents/{agent_id}/workflows

Each workflow, the details it asks for (fields) and how many conversations have followed it.

Any key

Path parameters

  • agent_idstringrequired

    Your 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"
Response
{
  "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

GET/agents/{agent_id}/workflows/channels

Each 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_idstringrequired

    Your 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"
Response
{
  "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

GET/agents/{agent_id}/workflows/templates

Ready-made workflows to start from: order, booking and lead. Pass a key as template when you create one.

Any key

Path parameters

  • agent_idstringrequired

    Your 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"
Response
{
  "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

POST/agents/{agent_id}/workflows

From a template, from your own steps, or blank. moved_from lists other workflows a channel was taken from.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • typestring

    What it's for: chat (the agent writes) or voice (calls: the agent speaks). Its channels must be that kind. Leave it out and it's worked out from channels. Workflows made before this can be null: on both kinds.

  • templatestring

    Start from a template: order, booking or lead.

  • namestring

    Up to 120 characters.

  • goalstring

    What it's for, up to 600 characters.

  • stepsobject[]

    The steps, in order. Each is {id, kind, title, text} with kind one of say, ask, decide, do or end. An ask step has fields ({label, kind, required, options}, where kind is text, phone, email, number, date, address or choice). A decide step has branches ({when, goto}). A do step has an action: save the details, hand to a person, use an app (its name in app), send to your webhook endpoints, or other. next (a step's id) 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's type: web_call is for voice, the rest for chat. A channel follows one workflow at a time, so it's taken off any other.

  • enabledboolean

    On (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"
    ]
  }'
Response
{
  "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

GET/agents/{agent_id}/workflows/{workflow_id}

One workflow with all its steps.

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • workflow_idstringrequired

    The workflow's ID.

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

PATCH/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • workflow_idstringrequired

    The workflow's ID.

Body

  • namestring

    Up to 120 characters.

  • goalstring

    Up to 600 characters.

  • enabledboolean

    On or off.

  • typestring

    chat or voice. Change it with channels of that kind.

  • stepsobject[]

    The steps, in order. Each is {id, kind, title, text} with kind one of say, ask, decide, do or end. An ask step has fields ({label, kind, required, options}, where kind is text, phone, email, number, date, address or choice). A decide step has branches ({when, goto}). A do step has an action: save the details, hand to a person, use an app (its name in app), send to your webhook endpoints, or other. next (a step's id) 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's type: web_call is for voice, the rest for chat. 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"
    ]
  }'
Response
{
  "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

POST/agents/{agent_id}/workflows/{workflow_id}/duplicate

A copy, on no channels, to change without touching the original.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • workflow_idstringrequired

    The 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"
Response
{
  "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

DELETE/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • workflow_idstringrequired

    The workflow's ID.

curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/agents/{agent_id}/test

A 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • messagestringrequired

    Up to 2,000 characters.

  • conversation_idstring

    Carry 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?"
  }'
Response
{
  "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

GET/agents/{agent_id}/artifacts

Newest first, up to 200.

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Query parameters

  • kindstring

    Only file (shared documents), image (shared photos) or made (written by the agent).

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/agents/{agent_id}/artifacts

A photo (PNG, JPG, WebP, GIF) or document for your agent, up to about 5 MB.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • namestringrequired

    The file's name, with its extension.

  • datastringrequired

    The 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..."
  }'
Response
{
  "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

GET/agents/{agent_id}/artifacts/{artifact_id}

One artifact, with the text the agent reads from it.

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • artifact_idstringrequired

    The artifact's ID.

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/agents/{agent_id}/artifacts/{artifact_id}/file

The file itself, with its own content type. A document the agent wrote comes as Markdown.

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • artifact_idstringrequired

    The artifact's ID.

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID/file \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
(the file)

Add it to knowledge

POST/agents/{agent_id}/artifacts/{artifact_id}/knowledge

Adds what the artifact says to the knowledge base made for this agent, and returns the new document.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • artifact_idstringrequired

    The 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"
Response
{
  "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

DELETE/agents/{agent_id}/artifacts/{artifact_id}

The agent can't send it any more.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • artifact_idstringrequired

    The artifact's ID.

curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/agents/{agent_id}/channels

type 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_idstringrequired

    Your 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"
Response
{
  "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

GET/agents/{agent_id}/channels/{channel_id}

One channel.

Any key

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • channel_idstringrequired

    The channel's ID.

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/channels/$CHANNEL_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

PATCH/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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

  • channel_idstringrequired

    The channel's ID.

Body

  • enabledboolean

    The channel is on.

  • connectorsstring[]

    The connectors (their IDs) the agent may use on this channel.

  • all_connectorsboolean

    true lets it use every connector, including ones added later.

  • chatboolean

    Website chat: typed chat on or off.

  • websiteobject

    Website chat: websites (up to 20), color (#6E56CF), position (left or right) and style (theme: light/dark, shape: rounded/soft/square, launcher_text, subtitle, up to 4 starters).

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?"
        ]
      }
    }
  }'
Response
{
  "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

GET/agents/{agent_id}/chat-settings

The agent's chat settings.

Any key

Path parameters

  • agent_idstringrequired

    Your 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"
Response
{
  "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

PATCH/agents/{agent_id}/chat-settings

Send only what changes.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • jobobject

    jobs: any of answer, sell, orders, bookings, support, explain. tone: friendly, professional, short or detailed. person: when to bring in your team, in your words.

  • instructionsstring

    Anything it should always know or do, up to 20,000 characters.

  • thinkingboolean

    Think before answering: better on tricky questions, a little slower.

  • human_helpobject

    enabled; when: asked (when they ask for a person) or stuck (also when it can't help); message: what it says when it hands over.

  • handoff_contactstring

    Who 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"
    }
  }'
Response
{
  "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

GET/agents/{agent_id}/voice-settings

The agent's voice, its greeting, and the words it should hear right.

Any key

Path parameters

  • agent_idstringrequired

    Your 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"
Response
{
  "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

PATCH/agents/{agent_id}/voice-settings

Send only what changes. Switching calls on without voice minutes in your package returns 409.

Full access

Path parameters

  • agent_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Body

  • enabledboolean

    Voice calls from the website chat.

  • voicestring

    female, male, or a voice's id from List voices.

  • greetingstring

    What 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.

  • aboutstring

    One line on who calls and why (Shoppers calling a clothes store), up to 200 characters.

  • whatsapp_repliesboolean

    Answer 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"
    ]
  }'
Response
{
  "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

GET/agents/{agent_id}/voice-settings/vocabulary-suggestions

Names and terms from the agent's knowledge that aren't in its vocabulary yet.

Any key

Path parameters

  • agent_idstringrequired

    Your 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"
Response
{
  "object": "vocabulary_suggestions",
  "suggestions": [
    "Wythe Ave",
    "stonewashed",
    "cardigan"
  ]
}

List voices

GET/voices

The 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"
Response
{
  "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

GET/agents/{agent_id}/usage

Replies, 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_idstringrequired

    Your agent's ID (in the portal: the agent's address).

Query parameters

  • monthstring

    YYYY-MM (month 01 to 12). This month if left out.

curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/usage \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/account/webhooks

Your 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"
Response
{
  "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

POST/account/webhooks

A new endpoint. Its signing secret (whsec_...) is in this answer only: keep it to verify signatures.

Full accessKey that reaches this module

Body

  • urlstringrequired

    An https address on your server.

  • eventsstring[]required

    The event types to send, at least one.

  • descriptionstring

    What 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"
    ]
  }'
Response
{
  "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

GET/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_idstringrequired

    The webhook's ID.

curl https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

PATCH/account/webhooks/{webhook_id}

Send only what changes. Switching it back on clears its failures.

Full accessKey that reaches this module

Path parameters

  • webhook_idstringrequired

    The webhook's ID.

Body

  • urlstring

    An https address.

  • eventsstring[]

    The event types to send.

  • descriptionstring

    Up to 200 characters.

  • enabledboolean

    On 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"
    ]
  }'
Response
{
  "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

DELETE/account/webhooks/{webhook_id}

Events stop going to it at once.

Full accessKey that reaches this module

Path parameters

  • webhook_idstringrequired

    The webhook's ID.

curl -X DELETE https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
  "object": "webhook",
  "deleted": true
}

Roll its secret

POST/account/webhooks/{webhook_id}/secret

A new signing secret. The old one stops working at once.

Full accessKey that reaches this module

Path parameters

  • webhook_idstringrequired

    The webhook's ID.

curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/secret \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "object": "webhook_secret",
  "webhook_id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
  "secret": "whsec_1a2b3c4d5e6f..."
}

Send a test event

POST/account/webhooks/{webhook_id}/test

Sends a ping event now, and says how your server answered.

Full accessKey that reaches this module

Path parameters

  • webhook_idstringrequired

    The webhook's ID.

curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/test \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

GET/account/webhooks/{webhook_id}/deliveries

The last 50 deliveries to this endpoint, newest first, with what your server answered.

Any keyKey that reaches this module

Path parameters

  • webhook_idstringrequired

    The webhook's ID.

Query parameters

  • statusstring

    Only pending, delivered or failed.

curl https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/deliveries \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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

POST/account/webhooks/deliveries/{delivery_id}/retry

Sends it again now, whatever happened to it before.

Full accessKey that reaches this module

Path parameters

  • delivery_idstringrequired

    The delivery's ID.

curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/deliveries/$DELIVERY_ID/retry \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
Response
{
  "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.

message.replied
{
  "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.created

    ModuleCustomer Agents

    WhenA customer started a new conversation, on any channel.

  • message.received

    ModuleCustomer Agents

    WhenA customer sent a message.

  • message.replied

    ModuleCustomer Agents

    WhenYour agent replied to a customer (with how it was paid).

  • message.held

    ModuleCustomer Agents

    WhenA message wasn't answered by AI: no package, or this month's replies are used.

  • handoff.requested

    ModuleCustomer Agents

    WhenA customer asked for a person from your team.

  • conversation.ended

    ModuleCustomer Agents

    WhenYour agent ended a conversation: a workflow's End step, or a call it said goodbye on. The conversation's status is then closed, until the customer writes again.

  • details.saved

    ModuleCustomer Agents

    WhenYour agent saved details a workflow asks for (data.saved), such as a name or phone number.

  • workflow.webhook

    ModuleCustomer Agents

    WhenA conversation reached a workflow's Send to webhook step: data.workflow, data.step and every detail collected so far in data.details.

  • lead.created

    ModuleCustomer 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.synced

    ModuleKnowledge

    WhenA web page or website in a knowledge base was read again and had changed (data.doc_id, data.title, data.source).

  • knowledge.sync_failed

    ModuleKnowledge

    WhenA web page or website in a knowledge base couldn't be read again (data.error says why).

  • connector.needs_sign_in

    ModuleConnectors

    WhenA connector's sign-in ran out (data.connector_id, data.label): sign in again in the console so agents can use it.

  • ping

    ModuleAny

    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).

Node.js
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);
}
Python
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", ""))