conecto. Get started

DocsGet started

Quickstart

One call signs an agent up, and the next one does real work. This page shows both, then the balance and a top-up, in curl, Python and JavaScript.

View as Markdown Open in ChatGPT Open in Claude
On this page
  1. Sign up
  2. Keep the key
  3. Call a tool
  4. Check the balance
  5. Top up
  6. Connect over MCP
  7. Next

Sign up

POST https://api.conecto.chat/v1/signup makes the account and its first key. Send your agent's name as bot_name and accept_terms: true. That accepts the terms for the business you act for, so read them first at https://conecto.chat/terms.md. business_name and owner_email are optional. The request needs no key.

curl

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

Python

import requests

reply = requests.post(
    "https://api.conecto.chat/v1/signup",
    json={
        "bot_name": "Pip",
        "accept_terms": True,
        "business_name": "Halverson Cycle & Repair",
        "owner_email": "dana@halversoncycle.example",
    },
)
print(reply.status_code, reply.json())

JavaScript

const reply = await fetch("https://api.conecto.chat/v1/signup", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    bot_name: "Pip",
    accept_terms: true,
    business_name: "Halverson Cycle & Repair",
    owner_email: "dana@halversoncycle.example",
  }),
});
console.log(reply.status, await reply.json());

The reply, with status 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"
  }
}

The address in owner_email is the owner at once, with nothing to confirm. owner_note says what that means: only the owner raises limits, and the account's warnings and approval requests go to them. Accounts and people covers an account with no owner yet.

The free credit is $1, for one new account per network a day. A second signup from the same network that day still gets a key, and free_credit_note says why it got no credit.

Keep the key

The key starts with conecto_sk_ and the reply shows it once. Conecto keeps only a hash of it. Store it where your agent keeps secrets, like an environment variable, and send it on every call:

Header
Authorization: Bearer conecto_sk_...

A key spends the balance, so keep it out of prompts, logs and shared code. A lost key is gone for good: make another with POST /v1/keys from a key that works, or ask the owner to make one. Keys and scopes has the rest.

The samples below read the key from an environment variable:

Terminal
export CONECTO_KEY="conecto_sk_..."

Call a tool

Every tool is one call: POST https://api.conecto.chat/v1/tools/<name> with the tool's arguments as a JSON object. This one saves a contact in the CRM, for $0.01. It is the tool's documented call, made for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg, so its balance differs from a new account's.

curl

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

Python

import os
import requests

reply = requests.post(
    "https://api.conecto.chat/v1/tools/crm_save_contact",
    headers={"Authorization": f"Bearer {os.environ['CONECTO_KEY']}"},
    json={
        "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"],
    },
)
print(reply.status_code, reply.json())

JavaScript

const reply = await fetch("https://api.conecto.chat/v1/tools/crm_save_contact", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CONECTO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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"],
  }),
});
console.log(reply.status, await reply.json());

The reply:

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
  }
}

cost_usd is what the call cost and balance_usd what is left. result is the tool's own answer, and each tool's page in the tools directory shows it. A call that fails costs nothing. Calling tools explains every field, retries and calls that run in the background.

Check the balance

GET /v1/balance shows the balance, the key's daily budget, the account's monthly ceiling and where the month's free reads and downloads stand. The account_balance tool answers the same.

curl

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

Python

import os
import requests

reply = requests.get(
    "https://api.conecto.chat/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['CONECTO_KEY']}"},
)
print(reply.status_code, reply.json())

JavaScript

const reply = await fetch("https://api.conecto.chat/v1/balance", {
  headers: {
    Authorization: `Bearer ${process.env.CONECTO_KEY}`,
  },
});
console.log(reply.status, await reply.json());
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"
  }
}

Top up

Free credit works inside the business. Email, phone calls and documents sent to people outside it need one real top-up first. POST /v1/topups with an amount answers with a Stripe checkout link: open it, or hand it to the owner. A top-up is $5 to $5,000 in whole cents, with a 7% + $0.35 fee, and the first one is doubled, up to $20 extra.

curl

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

Python

import os
import requests

reply = requests.post(
    "https://api.conecto.chat/v1/topups",
    headers={"Authorization": f"Bearer {os.environ['CONECTO_KEY']}"},
    json={
        "amount_usd": 20,
        "po_number": "4500012345",
    },
)
print(reply.status_code, reply.json())

JavaScript

const reply = await fetch("https://api.conecto.chat/v1/topups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CONECTO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount_usd: 20,
    po_number: "4500012345",
  }),
});
console.log(reply.status, await reply.json());
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"
}

The credit lands within seconds of the payment. Money covers auto-reload, refunds and receipts for a company.

Connect over MCP

An MCP client connects one server for every area the key may use, https://api.conecto.chat/v1/mcp, with the same Authorization header. This adds Conecto to Claude Code:

Terminal
claude mcp add --transport http --scope user conecto https://api.conecto.chat/v1/mcp \
  --header "Authorization: Bearer $CONECTO_KEY"

Connect your agent shows the other ways in, and the setup pages give the steps for each agent.

Next

Updated . Every route, field and number here is read from the API's own code.