---
title: "REST API reference for Conecto's agent platform"
url: "https://conecto.chat/docs/api"
markdown: "https://conecto.chat/docs/api.md"
description: "Every route of Conecto's REST API: signing up, the balance, top-ups, auto-reload, limits, keys, calls and tool calls, with fields, statuses and examples."
section: "Reference"
published: 2026-10-19
updated: 2026-10-19
---

# REST API

The REST API signs an agent up, runs every tool and looks after the account. This page lists every route with what it takes, what it answers and an example.

## Basics

- **Base address.** `https://api.conecto.chat`. Every route below starts there.
- **Keys.** Send the key as `Authorization: Bearer <key>`. `X-Api-Key: <key>` works too. The routes for discovery need no key. [Keys and scopes](https://conecto.chat/docs/keys.md)
- **Bodies.** JSON, with `Content-Type: application/json`, up to 16 MB.
- **Amounts.** Strings in US dollars with as many decimals as they need, at least two, like `"$0.01"`. Amounts you send, like `amount_usd`, are numbers.
- **Times.** ISO 8601 in UTC, like `2026-10-14T08:00:00+00:00`.
- **Refusals.** A status of 400 or more, with `error` and `message`, and nothing charged. [Errors](https://conecto.chat/docs/errors.md)
- **OpenAPI.** https://api.conecto.chat/v1/openapi.json describes every route here and every tool.

The balance and the call log also have tools, `account_balance`, `account_list_calls` and `account_get_call`, so an agent on MCP reaches them too.

## Sign up and get a key

`POST https://api.conecto.chat/v1/signup`

Makes the account, its first key and $1 of free credit. With `join`, it makes a key on the company's account instead, for the team and areas the code names. That reply has `joined` and `scope`, and no free credit, ceiling, terms or `owner_note`.

It needs no key.

### Body

| Field | Type | What it is |
| --- | --- | --- |
| `bot_name` (required) | string | The bot's name, as the call log shows it. 1 to 80 characters. |
| `accept_terms` (required) | boolean | Must be true. It accepts the terms, with their data processing terms, for the business you act for. |
| `business_name` | string | The business the account is for. Without it the account is called after the bot. |
| `owner_email` | string (email) | The owner's address. It makes them the owner at once, with nothing to confirm. |
| `country` | string | The business's country as two letters, like US or DE. |
| `runtime` | string | What the agent runs in, like n8n or Claude Code. It shows beside the key. |
| `website` | string | The business's website. |
| `referral` | string | A Conecto partner's code, if a partner sent you. It only counts at signup. |
| `join` | string | A join code the company gave you, in place of signing up alone. |
| `accountable` | string | The person who answers for the key. |

### Reply 201

The key (shown once) and the balance.

| Field | Type | What it is |
| --- | --- | --- |
| `account_id` | integer | The account's number. |
| `business_name` | string | The business the account is for. |
| `key` | string | The key. It is shown once. |
| `key_note` | string | How to send the key. |
| `balance_usd` | string | What the account can spend now: its credit, less what running calls hold, plus the reload amount while auto-reload is on. |
| `free_credit_usd` | string | The free credit this signup got. |
| `free_credit_note` | string or null | Why this signup got no free credit, when it got none. |
| `daily_budget_usd` | string | This key's daily budget. |
| `monthly_ceiling_usd` | string | The account's monthly ceiling. |
| `owner_note` | string | What the owner email means: whether anyone has something to confirm, and who raises limits. |
| `terms` | object | The terms accepted: their version, their addresses and the business they were accepted for. |
| `next` | object | The next calls to make, in words. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 400 | [`invalid_input`](https://conecto.chat/docs/errors.md#invalid_input) | The arguments do not fit the tool: a field is missing, has the wrong type or is out of range, or a value is not one the tool takes. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl -X POST https://api.conecto.chat/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
    "bot_name": "Pip",
    "accept_terms": true,
    "business_name": "Halverson Cycle & Repair",
    "owner_email": "dana@halversoncycle.example"
  }'
```

Reply 201:

```json
{
  "account_id": 4127,
  "business_name": "Halverson Cycle & Repair",
  "key": "conecto_sk_4f9b2c7e1a8d3f6b0e5c9a2d7f1b4e8c",
  "key_note": "Shown once. Send it as \"Authorization: Bearer <key>\" on every call.",
  "balance_usd": "$1.00",
  "free_credit_usd": "$1.00",
  "free_credit_note": null,
  "daily_budget_usd": "$20.00",
  "monthly_ceiling_usd": "$100.00",
  "owner_note": "dana@halversoncycle.example is the owner now, with nothing to confirm: they sign in at conecto.chat/account/login with that address. Only the owner raises limits, and the account's warnings and approval requests go to them.",
  "terms": {
    "version": "2026-10-27",
    "url": "https://conecto.chat/terms",
    "privacy": "https://conecto.chat/privacy",
    "accepted_for": "Halverson Cycle & Repair"
  },
  "next": {
    "tools": "GET /v1/tools",
    "run": "POST /v1/tools/<name> with the arguments as a JSON object",
    "mcp": "Connect https://api.conecto.chat/mcp/<area> with the same Authorization header",
    "top_up": "POST /v1/topups {\"amount_usd\": 20}: your first top-up is doubled, up to $20 extra"
  }
}
```

## Check the balance

`GET https://api.conecto.chat/v1/balance`

The balance, this key's daily budget, the account's monthly ceiling, auto-reload and the month's free reads and downloads. With an empty balance it also says how to top up.

Send the key as `Authorization: Bearer <key>`.

### Reply 200

The balance and limits.

| Field | Type | What it is |
| --- | --- | --- |
| `balance_usd` | string | What the account can spend now: its credit, less what running calls hold, plus the reload amount while auto-reload is on. |
| `reserved_usd` | string | What running calls hold until they settle. |
| `daily_budget_usd` | string | This key's daily budget. |
| `monthly_ceiling_usd` | string | The account's monthly ceiling. |
| `auto_reload` | object | Whether auto-reload is on, and its amount. |
| `auto_reload.status` | string | `off`, `pending` (waiting for the first payment), `active` or `failed` (a card payment failed). |
| `auto_reload.amount_usd` | string | The reload amount. |
| `free_this_month` | object | The month's free reads and downloads: what is used, what was bought and when they start again. |
| `top_up` | string | Only when the balance is empty: how to top up. |
| `minimum_usd` | integer | Only when the balance is empty: the smallest top-up. |
| `fee` | string | Only when the balance is empty: the fee on a top-up. |
| `first_topup_offer` | string or null | Only when the balance is empty: the first top-up's bonus. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl https://api.conecto.chat/v1/balance \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "balance_usd": "$1.00",
  "reserved_usd": "$0.00",
  "daily_budget_usd": "$20.00",
  "monthly_ceiling_usd": "$100.00",
  "auto_reload": {
    "status": "off",
    "amount_usd": "$0.00"
  },
  "free_this_month": {
    "reads": {
      "free": 1000000,
      "used": 0,
      "bought": 0,
      "price_after": "$0.50 per 10,000 reads"
    },
    "downloads": {
      "free": "5 GB",
      "used": "0 bytes",
      "bought": "0 bytes",
      "free_bytes": 5368709120,
      "used_bytes": 0,
      "bought_bytes": 0,
      "price_after": "$0.30 per GB"
    },
    "resets_at": "2026-11-01T00:00:00+00:00"
  }
}
```

## List the credit added

`GET https://api.conecto.chat/v1/topups`

The newest 100 entries of credit added: top-ups, first top-up bonuses, auto-reloads and free credit. A top-up says until when the `account_refund_topup` tool can refund it.

Send the key as `Authorization: Bearer <key>`.

### Reply 200

The credit added.

| Field | Type | What it is |
| --- | --- | --- |
| `credits` | array of objects | The credit added, newest first: top-ups, first top-up bonuses, auto-reloads and free credit. |
| `credits[].id` | integer | The entry's number. `account_refund_topup` takes a top-up's number as `topup_id`. |
| `credits[].kind` | string | What added it: `topup`, `bonus`, `auto_reload` or `free_credit`. |
| `credits[].amount_usd` | string | The credit added. |
| `credits[].at` | string | When it was added. |
| `credits[].note` | string or null | Its note, like the purchase order number of a top-up. |
| `credits[].refundable_until` | string or null | Until when a top-up can be refunded. null once the window has closed or part of it was used. |
| `refunds` | string | How a top-up is refunded. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl https://api.conecto.chat/v1/topups \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "credits": [
    {
      "id": 813,
      "kind": "bonus",
      "amount_usd": "$20.00",
      "at": "2026-10-14T09:12:00+00:00",
      "note": "First top-up doubled"
    },
    {
      "id": 812,
      "kind": "topup",
      "amount_usd": "$20.00",
      "at": "2026-10-14T09:12:00+00:00",
      "note": "Top-up, PO 4500012345",
      "refundable_until": "2026-10-15T09:12:00+00:00"
    },
    {
      "id": 790,
      "kind": "free_credit",
      "amount_usd": "$1.00",
      "at": "2026-10-14T08:00:00+00:00",
      "note": "Free signup credit"
    }
  ],
  "refunds": "An unused top-up can be refunded within 24 hours with the account_refund_topup tool; the fee is kept."
}
```

## Top up the balance

`POST https://api.conecto.chat/v1/topups`

A Stripe checkout link to pay once for credit, from $5 to $5,000 in whole cents. `po_number` prints a purchase order number on the receipt and the invoice.

Send the key as `Authorization: Bearer <key>`.

### Body

| Field | Type | What it is |
| --- | --- | --- |
| `amount_usd` (required) | number | The credit to buy, in US dollars, in whole cents. |
| `po_number` | string | A purchase order number. It is printed on the receipt and the invoice. |

### Reply 201

A Stripe checkout link to pay once.

| Field | Type | What it is |
| --- | --- | --- |
| `checkout_url` | string | Stripe's checkout page. Open it, or hand it to the owner, and pay once. |
| `amount_usd` | string | The credit bought, before the fee. |
| `fee_usd` | string | The service fee on this top-up. |
| `total_usd` | string | What the card pays. |
| `first_topup_bonus_usd` | string | The bonus credit this top-up brings, when it is the account's first. |
| `credited_usd` | string | The credit the balance gets once it is paid. |
| `po_number` | string | The purchase order number, when one was given. |
| `how` | string | What happens next, in words. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 400 | [`invalid_input`](https://conecto.chat/docs/errors.md#invalid_input) | The arguments do not fit the tool: a field is missing, has the wrong type or is out of range, or a value is not one the tool takes. |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl -X POST https://api.conecto.chat/v1/topups \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 20, "po_number": "4500012345"}'
```

Reply 201:

```json
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3D4e5F6g7H8",
  "amount_usd": "$20.00",
  "fee_usd": "$1.75",
  "total_usd": "$21.75",
  "first_topup_bonus_usd": "$20.00",
  "credited_usd": "$40.00",
  "how": "Open the link, or hand it to your owner. Credit lands within seconds of payment.",
  "po_number": "4500012345"
}
```

## Check auto-reload

`GET https://api.conecto.chat/v1/auto-reload`

Whether auto-reload is on, and its amount.

Send the key as `Authorization: Bearer <key>`.

### Reply 200

Whether auto-reload is on, and its amount.

| Field | Type | What it is |
| --- | --- | --- |
| `status` | string | `off`, `pending` (waiting for the first payment), `active` or `failed` (a card payment failed). |
| `amount_usd` | string | The reload amount. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl https://api.conecto.chat/v1/auto-reload \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "status": "off",
  "amount_usd": "$20.00"
}
```

## Turn auto-reload on, or change its amount

`POST https://api.conecto.chat/v1/auto-reload`

When auto-reload is off, it answers 201 with a Stripe checkout link to pay once. After that the card is charged each time the bots use the amount, plus the top-up fee. When it is on, it changes the amount and answers 200. A scoped key answers `key_scope`.

Send the key as `Authorization: Bearer <key>`.

### Body

| Field | Type | What it is |
| --- | --- | --- |
| `amount_usd` | number | The reload amount in US dollars, in whole cents. Left out, it keeps the amount set before. |

### Reply 200

It was on: the new amount.

| Field | Type | What it is |
| --- | --- | --- |
| `status` | string | `pending` until the first payment, or `active` when it was on already. |
| `amount_usd` | string | The reload amount. |

### Reply 201

Pay once through the link to turn it on.

| Field | Type | What it is |
| --- | --- | --- |
| `status` | string | `pending` until the first payment, or `active` when it was on already. |
| `checkout_url` | string | Stripe's checkout page. Open it, or hand it to the owner, and pay once. |
| `amount_usd` | string | The reload amount. |
| `how` | string | What happens next, in words. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 400 | [`invalid_input`](https://conecto.chat/docs/errors.md#invalid_input) | The arguments do not fit the tool: a field is missing, has the wrong type or is out of range, or a value is not one the tool takes. |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`key_scope`](https://conecto.chat/docs/errors.md#key_scope) | The key's scope doesn't cover this: another area, a tool it isn't given or is denied, a change by a read-only key, or a setting only a key without limits changes. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |
| 503 | [`unavailable`](https://conecto.chat/docs/errors.md#unavailable) | The tool, or a service it needs, is not available right now (or not switched on yet). Nothing was charged. |

### Example

Request:

```bash
curl -X POST https://api.conecto.chat/v1/auto-reload \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 20}'
```

Reply 201:

```json
{
  "status": "pending",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_b2C3d4E5f6G7h8I9",
  "amount_usd": "$20.00",
  "how": "Pay once through the link; after that the card is charged automatically each time your bots use the reload amount, plus the 7% + $0.35 fee each time."
}
```

## Turn auto-reload off

`DELETE https://api.conecto.chat/v1/auto-reload`

Turns auto-reload off, and a last invoice bills the usage left. A scoped key answers `key_scope`.

Send the key as `Authorization: Bearer <key>`.

### Reply 200

Off.

| Field | Type | What it is |
| --- | --- | --- |
| `status` | string | `off`. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`key_scope`](https://conecto.chat/docs/errors.md#key_scope) | The key's scope doesn't cover this: another area, a tool it isn't given or is denied, a change by a read-only key, or a setting only a key without limits changes. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl -X DELETE https://api.conecto.chat/v1/auto-reload \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "status": "off"
}
```

## Check the limits

`GET https://api.conecto.chat/v1/limits`

This key's daily budget and the account's monthly ceiling.

Send the key as `Authorization: Bearer <key>`.

### Reply 200

This key's daily budget and the account's monthly ceiling.

| Field | Type | What it is |
| --- | --- | --- |
| `daily_budget_usd` | string | This key's daily budget. |
| `monthly_ceiling_usd` | string | The account's monthly ceiling. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl https://api.conecto.chat/v1/limits \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "daily_budget_usd": "$20.00",
  "monthly_ceiling_usd": "$100.00"
}
```

## Lower the limits

`PATCH https://api.conecto.chat/v1/limits`

Lowers this key's daily budget or the account's monthly ceiling, at any time. On an account with an owner email, raising either is the owner's and answers `owner_required`. A scoped key answers `key_scope`.

Send the key as `Authorization: Bearer <key>`.

### Body

| Field | Type | What it is |
| --- | --- | --- |
| `daily_budget_usd` | number | Its daily budget. On an account with an owner email, at most this key's. |
| `monthly_ceiling_usd` | number | The account's monthly ceiling. |

### Reply 200

The limits now.

| Field | Type | What it is |
| --- | --- | --- |
| `daily_budget_usd` | string | This key's daily budget. |
| `monthly_ceiling_usd` | string | The account's monthly ceiling. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 400 | [`invalid_input`](https://conecto.chat/docs/errors.md#invalid_input) | The arguments do not fit the tool: a field is missing, has the wrong type or is out of range, or a value is not one the tool takes. |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`key_scope`](https://conecto.chat/docs/errors.md#key_scope) | The key's scope doesn't cover this: another area, a tool it isn't given or is denied, a change by a read-only key, or a setting only a key without limits changes. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 403 | [`owner_required`](https://conecto.chat/docs/errors.md#owner_required) | Only the owner may raise a spending limit or give a new key more daily budget than the key making it. The account page's own tools, and asking Conecto for a higher limit, take the owner, an admin or a key of the company-wide team without limits. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl -X PATCH https://api.conecto.chat/v1/limits \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"daily_budget_usd": 10}'
```

Reply 200:

```json
{
  "daily_budget_usd": "$10.00",
  "monthly_ceiling_usd": "$100.00"
}
```

## List the keys

`GET https://api.conecto.chat/v1/keys`

The account's keys that work, with their scopes. `current` marks the key making the call.

Send the key as `Authorization: Bearer <key>`.

### Reply 200

The keys that work.

| Field | Type | What it is |
| --- | --- | --- |
| `keys` | array of objects | The account's keys that work. |
| `keys[].key_id` | integer | The key's number. `DELETE /v1/keys/{key_id}` revokes it. |
| `keys[].bot_name` | string | The name it was made with. |
| `keys[].runtime` | string | What it runs in, when it said. |
| `keys[].last4` | string | The key's last four characters. |
| `keys[].daily_budget_usd` | string | Its daily budget. |
| `keys[].current` | boolean | true for the key making this call. |
| `keys[].scope` | object | What the key may do: its areas, tools, tools it may not run, reading only, drafts only, end date, networks, team and the person who answers for it. null means no limit. |
| `keys[].scope.areas` | array or null | The areas it works in. |
| `keys[].scope.tools` | array or null | The only tools it may run. |
| `keys[].scope.deny_tools` | array or null | Tools it may not run. |
| `keys[].scope.read_only` | boolean | It only reads. |
| `keys[].scope.drafts_only` | boolean | Every change it makes waits for a person. |
| `keys[].scope.expires_at` | string or null | It stops working at this time, as ISO 8601 with its offset. |
| `keys[].scope.networks` | array or null | The addresses or ranges it may be used from. |
| `keys[].scope.team` | string or null | Its team. |
| `keys[].scope.accountable` | string or null | The person who answers for the key. |
| `keys[].last_used_at` | string or null | When it last made a call. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl https://api.conecto.chat/v1/keys \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "keys": [
    {
      "key_id": 4127,
      "bot_name": "Pip",
      "runtime": "n8n",
      "last4": "4e8c",
      "daily_budget_usd": "$20.00",
      "current": true,
      "scope": {
        "areas": null,
        "tools": null,
        "deny_tools": null,
        "read_only": false,
        "drafts_only": false,
        "expires_at": null,
        "networks": null,
        "team": "Company",
        "accountable": null
      },
      "last_used_at": "2026-10-14T09:30:00+00:00"
    }
  ]
}
```

## Make a key

`POST https://api.conecto.chat/v1/keys`

A key for another bot or job, within this key's scope and team. It shares the daily budget of its line's first key. An account has at most 25 keys that work.

Send the key as `Authorization: Bearer <key>`.

### Body

| Field | Type | What it is |
| --- | --- | --- |
| `bot_name` (required) | string | The bot's name, as the call log shows it. 1 to 80 characters. |
| `runtime` | string | What the agent runs in, like n8n or Claude Code. It shows beside the key. |
| `daily_budget_usd` | number | Its daily budget. On an account with an owner email, at most this key's. |
| `areas` | array of strings | The areas it works in. |
| `tools` | array of strings | The only tools it may run. |
| `deny_tools` | array of strings | Tools it may not run. |
| `read_only` | boolean | It only reads. |
| `drafts_only` | boolean | Every change it makes waits for a person. |
| `expires_in_days` | integer | It stops working after this many days. |
| `expires_at` | string (date-time) | It stops working at this time, as ISO 8601 with its offset. |
| `networks` | array of strings | The addresses or ranges it may be used from. |
| `team` | string | Its team. Only a key of the company-wide team with no limits names another team, and a new name makes it. |
| `accountable` | string | The person who answers for the key. |

### Reply 201

The new key (shown once) and its scope.

| Field | Type | What it is |
| --- | --- | --- |
| `key_id` | integer | The new key's number. |
| `key` | string | The key. It is shown once. |
| `key_note` | string | How to send the key. |
| `daily_budget_usd` | string | This key's daily budget. |
| `scope` | object | What the key may do: its areas, tools, tools it may not run, reading only, drafts only, end date, networks, team and the person who answers for it. null means no limit. A person's own assistant shows the person and their teams. |
| `scope.areas` | array or null | The areas it works in. |
| `scope.tools` | array or null | The only tools it may run. |
| `scope.deny_tools` | array or null | Tools it may not run. |
| `scope.read_only` | boolean | It only reads. |
| `scope.drafts_only` | boolean | Every change it makes waits for a person. |
| `scope.expires_at` | string or null | It stops working at this time, as ISO 8601 with its offset. |
| `scope.networks` | array or null | The addresses or ranges it may be used from. |
| `scope.team` | string or null | Its team. |
| `scope.accountable` | string or null | The person who answers for the key. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 400 | [`invalid_input`](https://conecto.chat/docs/errors.md#invalid_input) | The arguments do not fit the tool: a field is missing, has the wrong type or is out of range, or a value is not one the tool takes. |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 403 | [`owner_required`](https://conecto.chat/docs/errors.md#owner_required) | Only the owner may raise a spending limit or give a new key more daily budget than the key making it. The account page's own tools, and asking Conecto for a higher limit, take the owner, an admin or a key of the company-wide team without limits. |
| 403 | [`scope_too_wide`](https://conecto.chat/docs/errors.md#scope_too_wide) | A new key can't be wider than the key making it: more areas or tools, other networks, or a later expiry. |
| 409 | [`limit_reached`](https://conecto.chat/docs/errors.md#limit_reached) | The business has as many of these as it may: keys, tables, schedules, pages, channels and the like. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl -X POST https://api.conecto.chat/v1/keys \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_name": "Support bot",
    "areas": ["helpdesk"],
    "drafts_only": true,
    "expires_at": "2027-01-31T18:00:00Z",
    "networks": ["203.0.113.0/24"],
    "team": "Support",
    "accountable": "Lena Brandt"
  }'
```

Reply 201:

```json
{
  "key_id": 4128,
  "key": "conecto_sk_9d2e7b4a1c6f3e8b5a0d7c2f9e4b1a6d",
  "key_note": "Shown once.",
  "daily_budget_usd": "$20.00",
  "scope": {
    "areas": ["helpdesk"],
    "tools": null,
    "deny_tools": null,
    "read_only": false,
    "drafts_only": true,
    "expires_at": "2027-01-31T18:00:00+00:00",
    "networks": ["203.0.113.0/24"],
    "team": "Support",
    "accountable": "Lena Brandt"
  }
}
```

## Revoke a key

`DELETE https://api.conecto.chat/v1/keys/{key_id}`

A key revokes itself and the keys made from it, and the first key of a line revokes any key of its line.

Send the key as `Authorization: Bearer <key>`.

### Parameters

| Parameter | In | Type | What it is |
| --- | --- | --- | --- |
| `key_id` | path | integer | The new key's number. |

### Reply 200

Revoked.

| Field | Type | What it is |
| --- | --- | --- |
| `revoked` | integer | The number of the key revoked. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 403 | [`not_yours`](https://conecto.chat/docs/errors.md#not_yours) | A key revokes itself and the keys made from it. The first key of a line revokes any key of its line. |
| 404 | [`not_found`](https://conecto.chat/docs/errors.md#not_found) | The thing named does not exist for this business: a record, a file, a call, a key or a page. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl -X DELETE https://api.conecto.chat/v1/keys/4128 \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "revoked": 4128
}
```

## List recent calls

`GET https://api.conecto.chat/v1/calls`

The account's calls, newest first. A scoped key sees its own calls only.

Send the key as `Authorization: Bearer <key>`.

### Parameters

| Parameter | In | Type | What it is |
| --- | --- | --- | --- |
| `limit` | query | integer | How many calls to list, newest first. |
| `status` | query | string | Only the calls in this state. |

### Reply 200

The calls.

| Field | Type | What it is |
| --- | --- | --- |
| `calls` | array of objects | The calls, newest first. |
| `calls[].call_id` | string | The call's id. |
| `calls[].tool` | string | The tool called. |
| `calls[].area` | string | The tool's area. |
| `calls[].status` | string | Where the call is: `reserved` (waiting to run), `running`, `succeeded` or `failed`. |
| `calls[].cost_usd` | string | What the call cost. A call that fails costs $0.00. |
| `calls[].error` | string or null | The error code of a call that failed. |
| `calls[].message` | string or null | What went wrong, in words. |
| `calls[].latency_ms` | integer or null | How long the tool took, in milliseconds. |
| `calls[].at` | string | When the call was made. |
| `calls[].bot` | string or null | The name of the key that made it. |
| `calls[].person` | string or null | Whose agent it was: the person the key belongs to, by name or email. null for a bot's own key. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl https://api.conecto.chat/v1/calls?limit=20&status=succeeded \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "calls": [
    {
      "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
      "tool": "crm_save_contact",
      "area": "crm",
      "status": "succeeded",
      "cost_usd": "$0.01",
      "error": null,
      "message": null,
      "latency_ms": 84,
      "at": "2026-10-14T08:00:00+00:00",
      "bot": "Pip",
      "person": null
    }
  ]
}
```

## Get a call (poll background calls)

`GET https://api.conecto.chat/v1/calls/{call_id}`

One call with its status and cost, what it was given and what it answered. Poll it for a call that runs in the background.

Send the key as `Authorization: Bearer <key>`.

### Parameters

| Parameter | In | Type | What it is |
| --- | --- | --- | --- |
| `call_id` | path | string | The call's id. |

### Reply 200

The call, its status and cost, with what it was given and what it answered.

| Field | Type | What it is |
| --- | --- | --- |
| `call_id` | string | The call's id. |
| `tool` | string | The tool called. |
| `area` | string | The tool's area. |
| `status` | string | Where the call is: `reserved` (waiting to run), `running`, `succeeded` or `failed`. |
| `cost_usd` | string | What the call cost. A call that fails costs $0.00. |
| `error` | string or null | The error code of a call that failed. |
| `message` | string or null | What went wrong, in words. |
| `latency_ms` | integer or null | How long the tool took, in milliseconds. |
| `at` | string | When the call was made. |
| `bot` | string or null | The name of the key that made it. |
| `person` | string or null | Whose agent it was: the person the key belongs to, by name or email. null for a bot's own key. |
| `input` | object or null | The arguments it was given. A secret argument shows as [redacted]. |
| `output` | object or null | What it answered. |

### Errors

A refusal costs nothing and its `message` says what to do. Each code links to its fix.

| Status | Code | What it means |
| --- | --- | --- |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 404 | [`not_found`](https://conecto.chat/docs/errors.md#not_found) | The thing named does not exist for this business: a record, a file, a call, a key or a page. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |

### Example

Request:

```bash
curl https://api.conecto.chat/v1/calls/5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93 \
  -H "Authorization: Bearer $CONECTO_KEY"
```

Reply 200:

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "crm_save_contact",
  "area": "crm",
  "status": "succeeded",
  "cost_usd": "$0.01",
  "error": null,
  "message": null,
  "latency_ms": 84,
  "at": "2026-10-14T08:00:00+00:00",
  "bot": "Pip",
  "person": null,
  "input": {
    "email": "jana@weber-kuechenplanung.example",
    "name": "Jana Weber",
    "title": "Kitchen planner",
    "company": "Weber Küchenplanung",
    "phone": "+49 40 66969 120",
    "location": "Hamburg",
    "lifecycle_stage": "lead",
    "tags": ["trade", "test-kitchen-visit"]
  },
  "output": {
    "contact": {
      "id": 4107,
      "email": "jana@weber-kuechenplanung.example",
      "name": "Jana Weber",
      "title": "Kitchen planner",
      "company": "Weber Küchenplanung",
      "company_id": 4105,
      "phone": "+49 40 66969 120",
      "location": "Hamburg",
      "lifecycle_stage": "lead",
      "outreach_status": null,
      "notes": "",
      "tags": ["test-kitchen-visit", "trade"],
      "custom_fields": {},
      "archived": false,
      "updated_at": "2026-10-14T08:00:00+00:00"
    },
    "created": true
  }
}
```

## Call a tool

`POST https://api.conecto.chat/v1/tools/{name}`

Runs one of the 581 tools. The body is the tool's arguments as a JSON object, and each tool's page in the [tools directory](https://conecto.chat/tools.md) lists them. Send the key as `Authorization: Bearer <key>`.

### Headers

| Header | What it is |
| --- | --- |
| `Authorization` (required) | `Bearer` and the key. `X-Api-Key` with the key works too. |
| `Content-Type` | `application/json`. |
| `Idempotency-Key` | Any string up to 120 characters. The same key never charges twice. A longer one is kept as its SHA-256. |
| `X-Conecto-Approval` | The `approval_id` of a call a person approved. It lets that one call run. |

### Reply 200

The envelope every tool answers in. The tool's own answer is in `result`.

| Field | Type | What it is |
| --- | --- | --- |
| `call_id` | string | The call's id. |
| `tool` | string | The tool called. |
| `status` | string | `succeeded`. A call that runs in the background answers `running` first, with status 202. |
| `replayed` | boolean | true when the reply repeats an earlier call with the same Idempotency-Key. A replay costs nothing. |
| `cost_usd` | string | What the call cost. A call that fails costs $0.00. |
| `balance_usd` | string | What the account can spend now: its credit, less what running calls hold, plus the reload amount while auto-reload is on. |
| `result` | object | What the tool answered. Each tool's page shows its result. |
| `bought` | object | Only on a read that bought the month's next block of reads: what it bought and what that cost, as a call of its own. |

### Reply 202

A tool that runs in the background answers `202` at once with `status: "running"`. Poll [`GET /v1/calls/{call_id}`](https://conecto.chat/docs/api.md#get-v1-calls-call-id) or the `account_get_call` tool until `status` is `succeeded` or `failed`. The call is charged only when it succeeds.

### Refusals

A refusal answers with a status of 400 or more, and `cost_usd` is `$0.00`. These codes come from the API before or around the tool's own work. Each tool's page lists the codes the tool itself can give.

| Field | Type | What it is |
| --- | --- | --- |
| `error` | string | The error code of a call that failed. |
| `message` | string | What went wrong, in words. |
| `cost_usd` | string | What the call cost. A call that fails costs $0.00. |
| `details` | object | What is needed to fix it, when there is something to add. |

| Status | Code | What it means |
| --- | --- | --- |
| 400 | [`invalid_input`](https://conecto.chat/docs/errors.md#invalid_input) | The arguments do not fit the tool: a field is missing, has the wrong type or is out of range, or a value is not one the tool takes. |
| 401 | [`key_expired`](https://conecto.chat/docs/errors.md#key_expired) | The key has expired. |
| 401 | [`unauthorized`](https://conecto.chat/docs/errors.md#unauthorized) | The call has no key, or the key is wrong or revoked. |
| 402 | [`insufficient_balance`](https://conecto.chat/docs/errors.md#insufficient_balance) | The balance cannot cover the most this call can cost, or the next reads or downloads once the month's free ones are used (a download link answers it to whoever opens it). |
| 402 | [`purchased_credit_required`](https://conecto.chat/docs/errors.md#purchased_credit_required) | AI visibility and the phone (calls, minutes and a number's rent) run only on credit bought with a top-up, never on free, beta or bonus credit, and the credit bought left cannot cover the most this call can cost. |
| 403 | [`account_paused`](https://conecto.chat/docs/errors.md#account_paused) | The owner paused every bot of the account. |
| 403 | [`key_scope`](https://conecto.chat/docs/errors.md#key_scope) | The key's scope doesn't cover this: another area, a tool it isn't given or is denied, a change by a read-only key, or a setting only a key without limits changes. |
| 403 | [`network_not_allowed`](https://conecto.chat/docs/errors.md#network_not_allowed) | The key may only be used from the networks it was given. |
| 403 | [`no_approver`](https://conecto.chat/docs/errors.md#no_approver) | Nobody but the person asking can approve this call, and nobody approves their own. |
| 403 | [`other_team`](https://conecto.chat/docs/errors.md#other_team) | The record belongs to another team. Every team reads it. Its own team changes it. |
| 403 | [`team_paused`](https://conecto.chat/docs/errors.md#team_paused) | The key's team is paused, so its keys can't run tools. |
| 404 | [`not_found`](https://conecto.chat/docs/errors.md#not_found) | The thing named does not exist for this business: a record, a file, a call, a key or a page. |
| 404 | [`unknown_tool`](https://conecto.chat/docs/errors.md#unknown_tool) | No tool has that name, or a background call's tool is gone. |
| 409 | [`approval_required`](https://conecto.chat/docs/errors.md#approval_required) | A person must approve this exact call first: an approval rule holds the tool, the key or its team is set to drafts only, or it gives a supplier new bank details. The request went to the approvers, each on a link of their own, and two people approve when the amount is over the rule's second line. Nothing was charged. |
| 409 | [`idempotency_key_reused`](https://conecto.chat/docs/errors.md#idempotency_key_reused) | The Idempotency-Key was used before for a different tool or different arguments. |
| 409 | [`in_progress`](https://conecto.chat/docs/errors.md#in_progress) | The same work is running right now: a call with this Idempotency-Key, an import, the reading of a scan, or an export of the account. |
| 413 | [`too_large`](https://conecto.chat/docs/errors.md#too_large) | The file, page or upload is over its size limit. |
| 429 | [`daily_budget_reached`](https://conecto.chat/docs/errors.md#daily_budget_reached) | The key reached its daily budget. Keys made from one key share that key's budget. |
| 429 | [`monthly_ceiling_reached`](https://conecto.chat/docs/errors.md#monthly_ceiling_reached) | The business reached its monthly spending ceiling. |
| 429 | [`rate_limited`](https://conecto.chat/docs/errors.md#rate_limited) | Too many calls in a short time: from this key or account, or to a service the tool uses (search, social posting, a site's analytics events), or more than three exports of the account in a day. |
| 429 | [`team_budget_reached`](https://conecto.chat/docs/errors.md#team_budget_reached) | The key's team spent its budget for this period, and the budget is hard. |
| 500 | [`internal_error`](https://conecto.chat/docs/errors.md#internal_error) | Something failed on Conecto's side. Nothing was charged. |
| 500 | [`secret_unreadable`](https://conecto.chat/docs/errors.md#secret_unreadable) | A background call's secret arguments could not be read back. Nothing was charged. |
| 503 | [`unavailable`](https://conecto.chat/docs/errors.md#unavailable) | The tool, or a service it needs, is not available right now (or not switched on yet). Nothing was charged. |

### Example

Request:

```bash
curl -X POST https://api.conecto.chat/v1/tools/crm_save_contact \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jana@weber-kuechenplanung.example",
    "name": "Jana Weber",
    "title": "Kitchen planner",
    "company": "Weber Küchenplanung",
    "phone": "+49 40 66969 120",
    "location": "Hamburg",
    "lifecycle_stage": "lead",
    "tags": ["trade", "test-kitchen-visit"]
  }'
```

Reply 200:

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "crm_save_contact",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.01",
  "balance_usd": "$19.75",
  "result": {
    "contact": {
      "id": 4107,
      "email": "jana@weber-kuechenplanung.example",
      "name": "Jana Weber",
      "title": "Kitchen planner",
      "company": "Weber Küchenplanung",
      "company_id": 4105,
      "phone": "+49 40 66969 120",
      "location": "Hamburg",
      "lifecycle_stage": "lead",
      "outreach_status": null,
      "notes": "",
      "tags": ["test-kitchen-visit", "trade"],
      "custom_fields": {},
      "archived": false,
      "updated_at": "2026-10-14T08:00:00+00:00"
    },
    "created": true
  }
}
```

Reply 202:

```json
{
  "call_id": "9b7e3c51-2f4a-4d8e-a0c6-71e5d2b8f4a3",
  "tool": "speech_transcribe",
  "status": "running",
  "reserved_usd": "$0.60",
  "poll": "GET /v1/calls/9b7e3c51-2f4a-4d8e-a0c6-71e5d2b8f4a3 (or the account_get_call tool) until status is succeeded or failed. You are charged only when it succeeds."
}
```

Reply 409:

```json
{
  "error": "approval_required",
  "approval_id": "3e9a6f12-5c7b-4d81-9f0e-2a6b8c4d1e57",
  "approver": "dana@halversoncycle.example",
  "message": "A person must approve this first: the request went to dana@halversoncycle.example. When notify.answered arrives (or notify_get_approval says Approve), call again with the same arguments and the approval (header X-Conecto-Approval, or _meta.approvalId over MCP). Nothing was charged.",
  "cost_usd": "$0.00"
}
```

## Routes for discovery

These answer without a key. An agent reads them to find out what Conecto has before it signs up.

### The index

`GET https://api.conecto.chat/v1`

What Conecto is, how to sign up, the prices in a few words and every area's MCP address.

Reply 200:

```json
{
  "name": "Conecto",
  "what": "The business backend for AI agents: CRM, email, phone, help desk, documents and more, paid per call.",
  "signup": {
    "method": "POST",
    "url": "https://api.conecto.chat/v1/signup",
    "body": {
      "bot_name": "string",
      "accept_terms": true,
      "business_name": "optional",
      "owner_email": "optional",
      "country": "optional, two letters",
      "runtime": "optional",
      "referral": "optional, a Conecto partner's code; only at signup"
    },
    "free_credit_usd": "$1.00"
  },
  "pricing": {
    "failed_calls": "never charged",
    "reads": "free up to 1,000,000 a month",
    "top_up_minimum_usd": "$5.00",
    "top_up_fee": "7% + $0.35",
    "first_top_up": "doubled, up to $20 extra",
    "catalog": "https://api.conecto.chat/v1/tools"
  },
  "areas": "https://api.conecto.chat/v1/areas",
  "mcp": {
    "analytics": "https://api.conecto.chat/mcp/analytics",
    "code": "https://api.conecto.chat/mcp/code",
    "crm": "https://api.conecto.chat/mcp/crm",
    "calendar": "https://api.conecto.chat/mcp/calendar",
    "chat": "https://api.conecto.chat/mcp/chat",
    "account": "https://api.conecto.chat/mcp/account",
    "admin": "https://api.conecto.chat/mcp/admin",
    "email": "https://api.conecto.chat/mcp/email",
    "helpdesk": "https://api.conecto.chat/mcp/helpdesk",
    "documents": "https://api.conecto.chat/mcp/documents",
    "esign": "https://api.conecto.chat/mcp/esign",
    "hiring": "https://api.conecto.chat/mcp/hiring",
    "outreach": "https://api.conecto.chat/mcp/outreach",
    "prospects": "https://api.conecto.chat/mcp/prospects",
    "lookups": "https://api.conecto.chat/mcp/lookups",
    "companies": "https://api.conecto.chat/mcp/companies",
    "longlists": "https://api.conecto.chat/mcp/longlists",
    "mergers": "https://api.conecto.chat/mcp/mergers",
    "valuation": "https://api.conecto.chat/mcp/valuation",
    "newsletters": "https://api.conecto.chat/mcp/newsletters",
    "notify": "https://api.conecto.chat/mcp/notify",
    "projects": "https://api.conecto.chat/mcp/projects",
    "schedules": "https://api.conecto.chat/mcp/schedules",
    "speech": "https://api.conecto.chat/mcp/speech",
    "uptime": "https://api.conecto.chat/mcp/uptime",
    "vault": "https://api.conecto.chat/mcp/vault",
    "web": "https://api.conecto.chat/mcp/web",
    "tables": "https://api.conecto.chat/mcp/tables",
    "links": "https://api.conecto.chat/mcp/links",
    "images": "https://api.conecto.chat/mcp/images",
    "files": "https://api.conecto.chat/mcp/files",
    "forms": "https://api.conecto.chat/mcp/forms",
    "helpcenter": "https://api.conecto.chat/mcp/helpcenter",
    "imports": "https://api.conecto.chat/mcp/imports",
    "invoices": "https://api.conecto.chat/mcp/invoices",
    "books": "https://api.conecto.chat/mcp/books",
    "inventory": "https://api.conecto.chat/mcp/inventory",
    "whistleblowing": "https://api.conecto.chat/mcp/whistleblowing",
    "connect": "https://api.conecto.chat/mcp/connect",
    "microsoft365": "https://api.conecto.chat/mcp/microsoft365",
    "googleworkspace": "https://api.conecto.chat/mcp/googleworkspace",
    "hubspot": "https://api.conecto.chat/mcp/hubspot",
    "salesforce": "https://api.conecto.chat/mcp/salesforce",
    "directory": "https://api.conecto.chat/mcp/directory",
    "hr": "https://api.conecto.chat/mcp/hr",
    "social": "https://api.conecto.chat/mcp/social",
    "purchasing": "https://api.conecto.chat/mcp/purchasing",
    "phone": "https://api.conecto.chat/mcp/phone",
    "websites": "https://api.conecto.chat/mcp/websites",
    "views": "https://api.conecto.chat/mcp/views",
    "visibility": "https://api.conecto.chat/mcp/visibility",
    "markets": "https://api.conecto.chat/mcp/markets"
  }
}
```

Its `reads` are free up to the month's 1,000,000 reads. Past that, each 10,000 more cost $0.50, as [Money](https://conecto.chat/docs/money.md#free-reads) explains.

### The areas

`GET https://api.conecto.chat/v1/areas`

Every area with its title, its summary, how many tools it has and its MCP address. There are 52. The first two:

Reply 200:

```json
{
  "areas": [
    {
      "area": "analytics",
      "title": "Website analytics",
      "summary": "Count a website's visits with one script tag, like Plausible or Umami: visitors, pages, sources, countries, devices and custom events. No cookies, and no IP addresses kept. $3 a month per site with 100,000 events.",
      "tools": 18,
      "mcp": "https://api.conecto.chat/mcp/analytics"
    },
    {
      "area": "code",
      "title": "Code",
      "summary": "Run Python or Node.js in a fresh sandbox with no network: files from the store go in, the files it writes come back. $0.0001 per second of run time, at least $0.005 a run.",
      "tools": 1,
      "mcp": "https://api.conecto.chat/mcp/code"
    }
  ]
}
```

### The tools

`GET https://api.conecto.chat/v1/tools`

Every tool with its name, area, title, description, price and whether it only reads, deletes data or runs in the background. Add `?area=crm` for one area. The CRM has 41. The first two:

Reply 200:

```json
{
  "tools": [
    {
      "name": "crm_find_contacts",
      "area": "crm",
      "title": "Find contacts",
      "description": "Search the CRM by name, email, company or phone, or by filters on any field, tag or custom field, or by a saved segment. Returns a page of contacts (most recently seen first unless `sort` says otherwise), the total, and next_offset for the next page.",
      "price": {
        "model": "free",
        "usd": "$0.00",
        "micros": 0
      },
      "read_only": true,
      "destructive": false,
      "runs_in_background": false
    },
    {
      "name": "crm_get_contact",
      "area": "crm",
      "title": "Get a contact",
      "description": "One contact with its tags, custom fields, recent activity, open tasks and deals, by id or email, and came_from: the website visit that led to their first chat, booking, form or signup (channel, source, campaign, landing page), when the site is counted. crm_timeline has everything that happened with them.",
      "price": {
        "model": "free",
        "usd": "$0.00",
        "micros": 0
      },
      "read_only": true,
      "destructive": false,
      "runs_in_background": false
    }
  ],
  "count": 41
}
```

### One tool

`GET https://api.conecto.chat/v1/tools/{name}`

One tool in full, with its input schema and examples. The same address with POST runs it.

Reply 200:

```json
{
  "name": "crm_save_contact",
  "area": "crm",
  "title": "Save a contact",
  "description": "Create a contact, or update the one with this email if it already exists. Only the fields you send change; tags are added, custom fields merged. Without an email a new contact is always created.",
  "price": {
    "model": "per_call",
    "usd": "$0.01",
    "micros": 10000
  },
  "read_only": false,
  "destructive": false,
  "runs_in_background": false,
  "input_schema": {
    "type": "object",
    "properties": {
      "email": {
        "type": "string",
        "maxLength": 254,
        "format": "email"
      },
      "name": {
        "type": "string",
        "maxLength": 255
      },
      "title": {
        "type": "string",
        "maxLength": 255
      },
      "company": {
        "type": "string",
        "maxLength": 255,
        "description": "Company name; also links or creates the company record."
      },
      "phone": {
        "type": "string",
        "maxLength": 60
      },
      "location": {
        "type": "string",
        "maxLength": 255
      },
      "timezone": {
        "type": "string",
        "maxLength": 60
      },
      "language": {
        "type": "string",
        "maxLength": 60
      },
      "lifecycle_stage": {
        "type": "string",
        "enum": [
          "lead",
          "trial",
          "onboarding",
          "customer",
          "at_risk",
          "churned",
          "advocate"
        ]
      },
      "notes": {
        "type": "string",
        "maxLength": 20000
      },
      "custom_fields": {
        "type": "object",
        "maxProperties": 60,
        "additionalProperties": {
          "type": ["string", "number", "boolean", "null"],
          "maxLength": 1000
        },
        "description": "Custom fields as {\"key\": value}, merged into the existing ones; null clears one. Keys defined with crm_define_field are checked against their type."
      },
      "tags": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "description": "Tags to add, e.g. [\"vip\"]; a new tag is made on first use. crm_tag_records removes tags."
      }
    },
    "required": [],
    "additionalProperties": false
  },
  "examples": [
    {
      "email": "ana@acme.com",
      "name": "Ana Ruiz",
      "company": "Acme",
      "lifecycle_stage": "lead",
      "tags": ["webinar-2026-10"],
      "custom_fields": {
        "plan": "Pro"
      }
    }
  ]
}
```

### SKILL.md

`GET https://api.conecto.chat/v1/skill.md`

The instructions an agent keeps, as Markdown. https://conecto.chat/SKILL.md answers the same. [For agents](https://conecto.chat/docs/for-agents.md) says what it holds.

### OpenAPI

`GET https://api.conecto.chat/v1/openapi.json`

OpenAPI 3.1.0 with every REST route above and every tool, 590 paths in all. One area at a time: `/v1/openapi/<area>.json` (OpenAPI 3.0, for a custom GPT's Actions) and `/v1/openapi/<area>.swagger.json` (OpenAPI 2.0 with the key in `X-Api-Key`, for Power Automate and Copilot Studio).

### MCP servers

`POST https://api.conecto.chat/mcp/{area}`

One MCP server per area, over Streamable HTTP. It answers JSON-RPC messages as plain JSON. `initialize` and `tools/list` need no key. `tools/call` needs the key in the `Authorization` header. A batch holds up to 50 messages. [Calling tools](https://conecto.chat/docs/calling-tools.md#over-mcp) has the details.

initialize, reply:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "conecto-crm",
      "version": "1.0.0",
      "title": "Conecto CRM"
    },
    "instructions": "Conecto CRM: Contacts, companies and deals in pipelines, with notes, tasks, tags, custom fields, saved segments, one search, full timelines, duplicate merging, bulk saves, reports and CSV export: the business's customer records. Every tool lists its price; reads are free up to 1,000,000 a month for the account (then $0.50 per 10,000), and a call that fails is never charged. Pay from your Conecto balance (GET https://api.conecto.chat/v1/balance)."
  }
}
```

### The connector with sign-in

`POST https://api.conecto.chat/v1/mcp`

One address for every area, for assistants that sign in with OAuth, like ChatGPT, Claude and Copilot. The person ticks the areas it may use when they sign in, and it lists those areas' tools. Without a key or a token it answers 401 and names its OAuth metadata.

Reply 401:

```json
{
  "error": "unauthorized",
  "message": "Sign in to connect: this server uses OAuth, or a Conecto key as \"Authorization: Bearer <key>\"."
}
```

The `WWW-Authenticate` header of that reply: `Bearer resource_metadata="https://api.conecto.chat/.well-known/oauth-protected-resource/v1/mcp", scope="tools"`

## More in the docs

- Previous: [Data and security](https://conecto.chat/docs/data-and-security.md)
- Next: [Errors](https://conecto.chat/docs/errors.md)
- Every page in one file: https://conecto.chat/docs/all.md
- Every page's title and address: https://conecto.chat/docs/index.json