# Marvoxa AI API reference

> The Marvoxa AI API lets your systems work with your Marvoxa AI account (AI customer agents for your website, WhatsApp, email and more) the way the portal does: talk to your agents, read and answer conversations, manage knowledge, workflows and settings, and get webhooks when something happens. Base URL: https://ai-api.marvoxa.com/v1. Docs: https://ai.marvoxa.com/docs/api

## 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:

```text
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:

```bash
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:

```text
/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.

Header:

```text
Authorization: Bearer mvx_sk_...
```

| Access | What it can do |
| --- | --- |
| 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. |

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

| usage.charge | Meaning |
| --- | --- |
| 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:

```bash
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`.

Error:

```json
{
  "error": {
    "type": "authentication_error",
    "message": "That API key isn't valid, or was revoked."
  }
}
```

| Status | type | When |
| --- | --- | --- |
| 401 | authentication_error | No key, or a wrong or revoked one. |
| 403 | permission_denied | The account is paused, the key's access level doesn't allow it, or the key doesn't reach this module. |
| 404 | not_found | The agent, conversation or item isn't one this key can reach. |
| 409 | conflict | Not 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 | invalid_request | A field is missing, too long or not one of the choices. |
| 429 | rate_limit_exceeded | Too many requests; wait a little and try again. |
| 502 | agent_error | The AI couldn't answer this time; try again. |

## 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 https://ai-api.marvoxa.com/v1/account`

Your business, its status and how many agents it has.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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).

Access: read.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/key \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/usage \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/settings`

Your business name, owner and industry.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/settings \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "object": "account_settings",
  "business_name": "Lumora Studio",
  "owner_name": "Sam Rivera",
  "owner_phone": "(718) 555-0136",
  "industry": "fashion"
}
```

#### Update settings

`PATCH https://ai-api.marvoxa.com/v1/account/settings`

Send only what changes.

Access: full, with a key for the whole account.

Body (JSON):

- `business_name` (string): Up to 160 characters.
- `owner_name` (string): Up to 120 characters.
- `owner_phone` (string): Digits, spaces, `+`, `-` and brackets.
- `industry` (string): Up to 40 characters.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/team`

Everyone on your team. `role` is `owner`, `admin` or `member`; `invited` means they haven't signed in yet.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/team \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Body (JSON):

- `name` (string, required): Up to 120 characters.
- `email` (string, required): Their email; they sign in with it.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/team/{user_id}`

`active: false` stops them signing in until restored.

Access: full, with a key for the whole account.

Path parameters:

- `user_id` (string, required): The team member's ID.

Body (JSON):

- `active` (boolean): Can sign in (true) or paused (false).

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/team/{user_id}`

They can't sign in any more.

Access: full, with a key for the whole account.

Path parameters:

- `user_id` (string, required): The team member's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/account/team/$USER_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/billing \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read, with a key for the whole account.

Query parameters:

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

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/usage \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/billing/invoices`

Your invoices, newest first. Totals are in US cents and paisa.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/billing/invoices \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/billing/invoices/{invoice_id}`

One invoice with its lines and exchange rate.

Access: read, with a key for the whole account.

Path parameters:

- `invoice_id` (string, required): The invoice's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/billing/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`.

Access: read, with a key for the whole account.

Query parameters:

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

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/billing/transactions \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/connectors \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/connectors/apps \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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).

Access: full, with a key for the whole account.

Body (JSON):

- `app` (string, required): The app's `slug`, from List apps.
- `understood` (boolean): You accept that a `private` app lets your agents read its conversations. Needed for those apps.
- `agent_id` (string): Attach it to this agent once it's live.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/connectors/{connection_id}`

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

Access: read, with a key for the whole account.

Path parameters:

- `connection_id` (string, required): The connection's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Path parameters:

- `connection_id` (string, required): The connection's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID/check \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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).

Access: full, with a key for the whole account.

Path parameters:

- `connection_id` (string, required): The connection's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/connectors/$CONNECTION_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`).

Access: full, with a key for the whole account.

Body (JSON):

- `kind` (string, required): `api` or `mcp`.
- `name` (string, required): What you and your agents call it (1 to 120 characters).
- `base_url` (string): An API's address, like `https://api.yourcompany.com/v1`. Needs `https`.
- `url` (string): An MCP server's address, like `https://mcp.yourcompany.com/mcp`. Needs `https`.
- `auth` (object, required): 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.
- `secrets` (object): 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).
- `headers` (array): An API's extra headers, sent with every call (up to 10): `[{name, value}]`. Their values are kept like keys.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/connectors/custom \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).

Body (JSON):

- `name` (string): Its name.
- `base_url` (string): An API's address.
- `url` (string): An MCP server's address.
- `auth` (object): How it signs in, as when connecting.
- `secrets` (object): New keys, as when connecting.
- `headers` (array): An API's extra headers: the whole list.
- `timeout_s` (integer): How long to wait for an answer, 2 to 30 seconds (a voice call waits 5 at most).
- `calls_per_minute` (integer): How often agents may call it, 1 to 600 a minute.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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).

Access: full, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "id": "b2d4f6a8-0c1e-4b3d-9f5a-7c9e1b3d5f7a",
  "object": "custom_connector",
  "deleted": true,
  "refunded_usd": "0.000000"
}
```

#### Test the connection

`POST https://ai-api.marvoxa.com/v1/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`.

Access: full, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/check \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "object": "connector_check",
  "ok": true,
  "status": 200,
  "ms": 212,
  "message": "Connected. The API answered in 212 ms."
}
```

#### List tools

`GET https://ai-api.marvoxa.com/v1/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`).

Access: read, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).

Body (JSON):

- `tools` (array, required): 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.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/connectors/custom/{custom_id}/tools/{tool_id}`

One tool, with how its last test went (`test_ok`).

Access: read, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).
- `tool_id` (string, required): The tool's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools/$TOOL_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`.

Access: full, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).
- `tool_id` (string, required): The tool's ID.

Body (JSON):

- `enabled` (boolean): Agents may use it.
- `changes` (boolean): It creates, changes or deletes something: the customer confirms before it runs.
- `name` (string): Its name.
- `description` (string): When agents should use it.
- `method` (string): The request's method (API tools).
- `path` (string): The request's path (API tools).
- `inputs` (array): What the agent fills in: the whole list (API tools).
- `fixed` (array): Values always sent: the whole list (API tools).
- `fields` (array): The reply's fields agents see; empty for all (API tools).
- `results_path` (string): Where the list sits in the reply (API tools).
- `max_results` (integer): Results agents get, 1 to 50 (API tools).

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).
- `tool_id` (string, required): The tool's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/tools/$TOOL_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "id": "d6f8a0c2-4e6b-4d8f-a1c3-5e7a9c1e3b5d",
  "object": "connector_tool",
  "deleted": true
}
```

#### Test a tool

`POST https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).
- `tool_id` (string, required): The tool's ID.

Body (JSON):

- `arguments` (object): The tool's inputs, by name, like `{"order_id": "LS-1042"}`.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`.

Access: read, with a key for the whole account.

Path parameters:

- `custom_id` (string, required): The custom connector's ID (the same as its connection's `id`).

Query parameters:

- `limit` (integer): How many, 1 to 200. Default 50.
- `before` (string): Calls before this time (an earlier answer's last `at`), for the next page.
- `status` (string): Only `ok`, `failed`, `waiting`, `confirmed` or `blocked` calls. Name several with commas.
- `tool` (string): Only this tool's calls (its `key`).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/connectors/custom/$CUSTOM_ID/activity?limit=20 \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Body (JSON):

- `url` (string): A link to the description, like `https://api.yourcompany.com/openapi.json`.
- `text` (string): The description itself.
- `file` (object): A file: `{name, data}`, with `data` in base64 or as a data URL.

Example:

```bash
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:

```json
{
  "object": "api_description",
  "title": "Lumora Studio Orders API",
  "base_url": "https://api.lumora.studio/v1",
  "auth": {
    "type": "api_key",
    "in": "header",
    "name": "X-API-Key"
  },
  "operations": [
    {
      "op": "getOrder",
      "key": "get_order",
      "name": "Get order",
      "description": "Returns one order by its number.",
      "method": "GET",
      "path": "/orders/{order_id}",
      "inputs": [
        {
          "name": "order_id",
          "in": "path",
          "type": "string",
          "required": true,
          "description": "The order number, like LS-1042.",
          "enum": null,
          "example": "LS-1042"
        }
      ],
      "changes": false,
      "tag": "Orders"
    },
    {
      "op": "cancelOrder",
      "key": "cancel_order",
      "name": "Cancel order",
      "description": "Cancels an order that hasn't been sent.",
      "method": "POST",
      "path": "/orders/{order_id}/cancel",
      "inputs": [
        {
          "name": "order_id",
          "in": "path",
          "type": "string",
          "required": true,
          "description": "The order number, like LS-1042.",
          "enum": null,
          "example": "LS-1042"
        },
        {
          "name": "reason",
          "in": "body",
          "type": "string",
          "required": false,
          "description": "Why the customer is cancelling, in their words.",
          "enum": null,
          "example": null
        }
      ],
      "changes": true,
      "tag": "Orders"
    }
  ],
  "truncated": false
}
```

## Knowledge bases

### Knowledge bases

In the portal: Brain › Knowledge.

What your agents know, kept in knowledge bases on your account: text you write, web pages and files. Each agent answers from the knowledge bases attached to it (Customer Agents › Knowledge bases), and one knowledge base can serve many agents. Your package's words per knowledge base apply, as in the portal (`word_limit`, null with no limit). Needs a key that reaches this module.

#### List knowledge bases

`GET https://ai-api.marvoxa.com/v1/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.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/knowledge-bases \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases`

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

Access: full, with a key for the whole account.

Body (JSON):

- `name` (string, required): Up to 120 characters.
- `description` (string): What's in it, up to 600 characters.
- `agent_ids` (string[]): Agents that read it from the start.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}`

One knowledge base, with its test questions and the documents in it that disagree.

Access: read, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}`

Send only what changes. `agent_ids` sets exactly which agents read it.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Body (JSON):

- `name` (string): Up to 120 characters.
- `description` (string): Up to 600 characters.
- `agent_ids` (string[]): Exactly these agents read it.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}`

Deletes it and every document in it. Agents reading it stop at once. This can't be undone.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}/documents`

Its documents, oldest first, without their text (get one for that), and its words against your package's limit.

Access: read, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}/documents`

A document from your own text.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Body (JSON):

- `title` (string, required): Up to 200 characters.
- `content` (string, required): The text, up to 100,000 characters.
- `kind` (string): What it is, in your words (`Menu`, `Delivery policy`). Default `text`.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Body (JSON):

- `url` (string, required): The page's address.
- `kind` (string): What it is, in your words (`Menu`, `Delivery policy`). Default `text`.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Body (JSON):

- `name` (string, required): The file's name, with its extension.
- `data` (string, required): The file as base64 (or a data URL).
- `kind` (string): What it is, in your words (`Menu`, `Delivery policy`). Default `text`.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}/documents/{doc_id}`

One document, with its text.

Access: read, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.
- `doc_id` (string, required): The document's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/$DOC_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}/documents/{doc_id}`

Send only what changes.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.
- `doc_id` (string, required): The document's ID.

Body (JSON):

- `title` (string): Up to 200 characters.
- `content` (string): Up to 100,000 characters.
- `kind` (string): What it is, in your words.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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).

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.
- `doc_id` (string, required): The document's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/$DOC_ID/resync \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}/documents/{doc_id}`

Agents stop using it at once.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.
- `doc_id` (string, required): The document's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/documents/$DOC_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Body (JSON):

- `question` (string, required): What a customer might ask, up to 500 characters.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Body (JSON):

- `question` (string, required): Up to 300 characters.
- `expect` (string, required): A word or phrase the answer must have, up to 120 characters.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}/tests/run`

Runs every test question again now.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/tests/run \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}/tests/{test_id}`

It stops running.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.
- `test_id` (string, required): The test question's `id`.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/tests/$TEST_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "id": "cfecbcba5166",
  "object": "knowledge_test",
  "deleted": true
}
```

#### Find documents that disagree

`POST https://ai-api.marvoxa.com/v1/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`).

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-bases/$KB_ID/check \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-bases/{kb_id}/conflicts/{conflict_id}`

Which side of a disagreement is right. Agents use it from their next reply.

Access: full, with a key for the whole account.

Path parameters:

- `kb_id` (string, required): The knowledge base's ID.
- `conflict_id` (string, required): The disagreement's `id`.

Body (JSON):

- `chosen` (string | null, required): `a` or `b`, or null to undo the choice.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/knowledge-gaps \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`).

Access: full, with a key for the whole account.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-gaps/scan \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "object": "knowledge_gap_scan",
  "added": 2,
  "price_usd": "0.000910"
}
```

#### Update a gap

`PATCH https://ai-api.marvoxa.com/v1/knowledge-gaps/{gap_id}`

Correct the question or answer, or choose the knowledge base it goes in. Send only what changes.

Access: full, with a key for the whole account.

Path parameters:

- `gap_id` (string, required): The gap's ID.

Body (JSON):

- `question` (string): Up to 300 characters.
- `answer` (string): Up to 2,000 characters.
- `knowledge_base_id` (string): The knowledge base it goes in.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-gaps/{gap_id}/add`

Adds the answer as a question-and-answer document (`document_id`). It needs an answer and a knowledge base.

Access: full, with a key for the whole account.

Path parameters:

- `gap_id` (string, required): The gap's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-gaps/$GAP_ID/add \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/knowledge-gaps/{gap_id}/dismiss`

It isn't listed again.

Access: full, with a key for the whole account.

Path parameters:

- `gap_id` (string, required): The gap's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/knowledge-gaps/$GAP_ID/dismiss \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "id": "f2b4d6f8-0a2c-4e6a-9b8d-0f2a4c6e8b0d",
  "object": "knowledge_gap",
  "deleted": true
}
```

## 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 https://ai-api.marvoxa.com/v1/agents`

The agents this key can reach, oldest first.

Access: read.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents`

A new agent, with website chat ready to add to your site. It answers once your account has a running package.

Access: full, with a key for the whole account.

Body (JSON):

- `name` (string, required): Its name, up to 80 characters.
- `language` (string): `auto` (answers in the customer's language), `en`, `ur` or `roman-ur`. Default `auto`.
- `greeting` (string): Its first message, up to 300 characters.
- `instructions` (string): Anything it should always know or do.
- `websites` (string[]): Websites its chat may load on (`lumora.studio`), up to 20.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}`

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

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `name` (string): Up to 80 characters.
- `language` (string): `auto`, `en`, `ur` or `roman-ur`.
- `greeting` (string): Up to 300 characters.
- `enabled` (boolean): Answering customers (true) or paused (false).

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `image` (string | null, required): `data:image/png;base64,...`, or null to remove it.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Query parameters:

- `confirm` (string): The agent's name, exactly. Needed once it has answered customers.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID?confirm=Ava \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: messages.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `message` (string, required): What the customer said. Up to 2,000 characters.
- `conversation_id` (string): Carry on this conversation. Leave it out to start a new one.
- `user` (string): Your own ID for the person, up to 100 characters.
- `stream` (boolean): Stream the reply as server-sent events: `conversation`, then `delta` pieces of text, then `done` with the whole message (or `error`).

Example:

```bash
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:

```json
{
  "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
  }
}
```

### 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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/conversations`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Query parameters:

- `channel` (string): Only one channel: `web`, `whatsapp`, `call` or `api`.
- `user` (string): Only this person's API conversations.
- `limit` (integer): How many, 1 to 100. Default 20.
- `before` (timestamp): For the next page: the last conversation's `last_message_at`.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations?limit=20 \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`).

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `conversation_id` (string, required): The conversation's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/conversations/{conversation_id}/messages`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `conversation_id` (string, required): The conversation's ID.

Query parameters:

- `limit` (integer): How many, 1 to 100. Default 50.
- `before` (string): For older messages: the first message's ID from the last page.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/messages \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `conversation_id` (string, required): The conversation's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/take \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `conversation_id` (string, required): The conversation's ID.

Body (JSON):

- `text` (string, required): Up to 4,000 characters.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/conversations/{conversation_id}/release`

Hands the conversation back to the agent.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `conversation_id` (string, required): The conversation's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/conversations/$CONVERSATION_ID/release \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Query parameters:

- `status` (string): Only one status: `new`, `contacted`, `won` or `lost`.
- `source` (string): `workflow` or `chat`.
- `channel` (string): Only one channel: `web`, `call`, `whatsapp` or `api`.
- `q` (string): Search names, phone numbers, emails, what they asked, details and notes.
- `since` (date): From this day (YYYY-MM-DD, Pakistan time), included.
- `until` (date): Up to this day, included.
- `limit` (integer): How many, 1 to 100. Default 20.
- `before` (timestamp): For the next page: the last lead's `created_at`.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads?status=new&limit=20 \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/settings \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "object": "lead_settings",
  "agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
  "capture": true
}
```

##### Update lead settings

`PATCH https://ai-api.marvoxa.com/v1/agents/{agent_id}/leads/settings`

Turns picking up leads from conversations on or off.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `capture` (boolean, required): On or off.

Example:

```bash
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:

```json
{
  "object": "lead_settings",
  "agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
  "capture": false
}
```

##### Get a lead

`GET https://ai-api.marvoxa.com/v1/agents/{agent_id}/leads/{lead_id}`

One lead.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `lead_id` (string, required): The lead's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/$LEAD_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `lead_id` (string, required): The lead's ID.

Body (JSON):

- `status` (string): `new`, `contacted`, `won` or `lost`.
- `note` (string): Your team's note, up to 4,000 characters.
- `name` (string): Up to 160 characters.
- `phone` (string): Up to 40 characters.
- `email` (string): Up to 200 characters.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/leads/{lead_id}`

Removes the lead. The conversation it came from stays.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `lead_id` (string, required): The lead's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/leads/$LEAD_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "id": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d5f",
  "object": "lead",
  "deleted": true
}
```

### 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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/knowledge-bases`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/knowledge-bases \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/knowledge-bases`

The agent answers from it from its next reply. Returns the knowledge base, with this agent in `agent_ids`.

Access: full, with a key for the whole account.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `knowledge_base_id` (string, required): One of your account's knowledge bases.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/knowledge-bases`

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

Access: full, with a key for the whole account.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `knowledge_base_ids` (string[], required): Up to 20.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/knowledge-bases/{kb_id}`

The agent stops reading it. The knowledge base stays on your account, for other agents.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `kb_id` (string, required): The knowledge base's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/knowledge-bases/$KB_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "id": "c3e5a7b9-1d3f-4a5c-8e7a-9b1d3f5a7c9e",
  "object": "knowledge_base",
  "agent_id": "3f6b2c1e-8a4d-4b7e-9c2f-1d5e7a9b0c3d",
  "detached": true
}
```

##### Let Marvoxa choose

`POST https://ai-api.marvoxa.com/v1/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`).

Access: full, with a key for the whole account.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/knowledge-bases/choose \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`).

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/connectors`

Attaches a live connection to the agent, free. The same connection can't be attached to one agent twice (`409`).

Access: full, with a key for the whole account.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `connection_id` (string, required): A live connection, from List connections.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/connectors/{connector_id}`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `connector_id` (string, required): The connector's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors/$CONNECTOR_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `connector_id` (string, required): The connector's ID.

Body (JSON):

- `enabled` (boolean): The agent may use the app.
- `actions` (object): `{"ACTION_KEY": false}`: switch actions on (true) or off (false), by their `key`.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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`).

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `connector_id` (string, required): The connector's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/connectors/$CONNECTOR_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/workflows`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/channels \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/workflows/templates`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/templates \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/workflows`

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

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `type` (string): 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.
- `template` (string): Start from a template: `order`, `booking` or `lead`.
- `name` (string): Up to 120 characters.
- `goal` (string): What it's for, up to 600 characters.
- `steps` (object[]): 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.
- `channels` (string[]): 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.
- `enabled` (boolean): On (default) or off.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/workflows/{workflow_id}`

One workflow with all its steps.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `workflow_id` (string, required): The workflow's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `workflow_id` (string, required): The workflow's ID.

Body (JSON):

- `name` (string): Up to 120 characters.
- `goal` (string): Up to 600 characters.
- `enabled` (boolean): On or off.
- `type` (string): `chat` or `voice`. Change it with `channels` of that kind.
- `steps` (object[]): 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.
- `channels` (string[]): 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.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/workflows/{workflow_id}/duplicate`

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

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `workflow_id` (string, required): The workflow's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID/duplicate \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/workflows/{workflow_id}`

Its channels answer normally again. Conversations under way that follow it carry on without it.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `workflow_id` (string, required): The workflow's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/workflows/$WORKFLOW_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/test`

A message from you to your agent. Send the `conversation_id` it returns to carry on the test.

Access: messages.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `message` (string, required): Up to 2,000 characters.
- `conversation_id` (string): Carry on this test.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/artifacts`

Newest first, up to 200.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Query parameters:

- `kind` (string): Only `file` (shared documents), `image` (shared photos) or `made` (written by the agent).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/artifacts`

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

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `name` (string, required): The file's name, with its extension.
- `data` (string, required): The file as base64 (or a data URL).

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/artifacts/{artifact_id}`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `artifact_id` (string, required): The artifact's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/artifacts/{artifact_id}/file`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `artifact_id` (string, required): The artifact's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID/file \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
(the file)
```

##### Add it to knowledge

`POST https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `artifact_id` (string, required): The artifact's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID/knowledge \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/artifacts/{artifact_id}`

The agent can't send it any more.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `artifact_id` (string, required): The artifact's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/artifacts/$ARTIFACT_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "id": "9a1b3c5d-7e9f-4a2b-8c4d-6e8f0a2b4c6d",
  "object": "artifact",
  "deleted": true
}
```

### 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 https://ai-api.marvoxa.com/v1/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.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/channels \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/channels/{channel_id}`

One channel.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `channel_id` (string, required): The channel's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/channels/$CHANNEL_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/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.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).
- `channel_id` (string, required): The channel's ID.

Body (JSON):

- `enabled` (boolean): The channel is on.
- `connectors` (string[]): The connectors (their IDs) the agent may use on this channel.
- `all_connectors` (boolean): true lets it use every connector, including ones added later.
- `chat` (boolean): Website chat: typed chat on or off.
- `website` (object): 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`).

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/chat-settings`

The agent's chat settings.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/chat-settings \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/chat-settings`

Send only what changes.

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `job` (object): `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.
- `instructions` (string): Anything it should always know or do, up to 20,000 characters.
- `thinking` (boolean): Think before answering: better on tricky questions, a little slower.
- `human_help` (object): `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_contact` (string): Who customers are pointed to when they want a person (a number or email), up to 200 characters.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/voice-settings`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/voice-settings \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/voice-settings`

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

Access: full.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Body (JSON):

- `enabled` (boolean): Voice calls from the website chat.
- `voice` (string): `female`, `male`, or a voice's `id` from List voices.
- `greeting` (string): What it says when it picks up, up to 300 characters.
- `vocabulary` (string[]): Names and words callers may say (products, brands, places), so it hears them right. Up to 300.
- `about` (string): One line on who calls and why (`Shoppers calling a clothes store`), up to 200 characters.
- `whatsapp_replies` (boolean): Answer a WhatsApp voice note with a voice note.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/agents/{agent_id}/voice-settings/vocabulary-suggestions`

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

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/voice-settings/vocabulary-suggestions \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "object": "vocabulary_suggestions",
  "suggestions": [
    "Wythe Ave",
    "stonewashed",
    "cardigan"
  ]
}
```

##### List voices

`GET https://ai-api.marvoxa.com/v1/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.

Access: read.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/voices \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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
}
```

### 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 https://ai-api.marvoxa.com/v1/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.

Access: read.

Path parameters:

- `agent_id` (string, required): Your agent's ID (in the portal: the agent's address).

Query parameters:

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

Example:

```bash
curl https://ai-api.marvoxa.com/v1/agents/$AGENT_ID/usage \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/webhooks`

Your webhook endpoints, and every event type you can choose (`events`).

Access: read, with a key for the whole account.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/webhooks \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/webhooks`

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

Access: full, with a key for the whole account.

Body (JSON):

- `url` (string, required): An https address on your server.
- `events` (string[], required): The event types to send, at least one.
- `description` (string): What it's for, up to 200 characters.
- `agent_ids` (string[]): Only events from these agents. Empty or left out: every agent, including ones you add later.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/webhooks/{webhook_id}`

One endpoint. `failures` counts failed deliveries in a row; at 50 it's switched off (`disabled_reason`).

Access: read, with a key for the whole account.

Path parameters:

- `webhook_id` (string, required): The webhook's ID.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/webhooks/{webhook_id}`

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

Access: full, with a key for the whole account.

Path parameters:

- `webhook_id` (string, required): The webhook's ID.

Body (JSON):

- `url` (string): An https address.
- `events` (string[]): The event types to send.
- `description` (string): Up to 200 characters.
- `enabled` (boolean): On or off.
- `agent_ids` (string[]): Only these agents; empty for every agent.

Example:

```bash
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:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/webhooks/{webhook_id}`

Events stop going to it at once.

Access: full, with a key for the whole account.

Path parameters:

- `webhook_id` (string, required): The webhook's ID.

Example:

```bash
curl -X DELETE https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
  "object": "webhook",
  "deleted": true
}
```

#### Roll its secret

`POST https://ai-api.marvoxa.com/v1/account/webhooks/{webhook_id}/secret`

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

Access: full, with a key for the whole account.

Path parameters:

- `webhook_id` (string, required): The webhook's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/secret \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "object": "webhook_secret",
  "webhook_id": "4c6e8a0b-2d4f-4c6e-8a0b-2d4f6a8c0e2a",
  "secret": "whsec_1a2b3c4d5e6f..."
}
```

#### Send a test event

`POST https://ai-api.marvoxa.com/v1/account/webhooks/{webhook_id}/test`

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

Access: full, with a key for the whole account.

Path parameters:

- `webhook_id` (string, required): The webhook's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/test \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/webhooks/{webhook_id}/deliveries`

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

Access: read, with a key for the whole account.

Path parameters:

- `webhook_id` (string, required): The webhook's ID.

Query parameters:

- `status` (string): Only `pending`, `delivered` or `failed`.

Example:

```bash
curl https://ai-api.marvoxa.com/v1/account/webhooks/$WEBHOOK_ID/deliveries \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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 https://ai-api.marvoxa.com/v1/account/webhooks/deliveries/{delivery_id}/retry`

Sends it again now, whatever happened to it before.

Access: full, with a key for the whole account.

Path parameters:

- `delivery_id` (string, required): The delivery's ID.

Example:

```bash
curl -X POST https://ai-api.marvoxa.com/v1/account/webhooks/deliveries/$DELIVERY_ID/retry \
  -H "Authorization: Bearer $MARVOXA_API_KEY"
```

Response:

```json
{
  "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:

```json
{
  "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`).

| Event | Module | When |
| --- | --- | --- |
| conversation.created | Customer Agents | A customer started a new conversation, on any channel. |
| message.received | Customer Agents | A customer sent a message. |
| message.replied | Customer Agents | Your agent replied to a customer (with how it was paid). |
| message.held | Customer Agents | A message wasn't answered by AI: no package, or this month's replies are used. |
| handoff.requested | Customer Agents | A customer asked for a person from your team. |
| conversation.ended | Customer Agents | Your 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 | Customer Agents | Your agent saved details a workflow asks for (`data.saved`), such as a name or phone number. |
| workflow.webhook | Customer Agents | A conversation reached a workflow's Send to webhook step: `data.workflow`, `data.step` and every detail collected so far in `data.details`. |
| lead.created | Customer Agents | A 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 | Knowledge | A web page or website in a knowledge base was read again and had changed (`data.doc_id`, `data.title`, `data.source`). |
| knowledge.sync_failed | Knowledge | A web page or website in a knowledge base couldn't be read again (`data.error` says why). |
| connector.needs_sign_in | Connectors | A connector's sign-in ran out (`data.connector_id`, `data.label`): sign in again in the console so agents can use it. |
| ping | Any | A 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:

```javascript
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:

```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", ""))
```
