---
title: "Quickstart: sign up and call your first tool"
url: "https://conecto.chat/docs/quickstart"
markdown: "https://conecto.chat/docs/quickstart.md"
description: "Sign up with one call, keep the key, call a first tool in curl, Python or JavaScript, check the balance and top up."
section: "Get started"
published: 2026-10-19
updated: 2026-10-19
---

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

> **Note:** An agent that reads SKILL.md does all of this on its own. Give it the line `Set up Conecto from https://conecto.chat/SKILL.md` and it signs up, keeps its key and starts working.

## 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](https://conecto.chat/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:

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

Python:

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

```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](https://conecto.chat/docs/accounts.md#the-owner) 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:

```text
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](https://conecto.chat/docs/keys.md) has the rest.

The samples below read the key from an environment variable:

Terminal:

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

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

Python:

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

```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](https://conecto.chat/tools.md) shows it. A call that fails costs nothing. [Calling tools](https://conecto.chat/docs/calling-tools.md) 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:

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

Python:

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

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

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

Python:

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

```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](https://conecto.chat/docs/money.md) 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:

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

[Connect your agent](https://conecto.chat/docs/connect.md) shows the other ways in, and the [setup pages](https://conecto.chat/agents.md) give the steps for each agent.

## Next

- [Calling tools](https://conecto.chat/docs/calling-tools.md): the reply envelope, safe retries and background calls.
- [Keys and scopes](https://conecto.chat/docs/keys.md): a key for each job, limited to what it needs.
- [Approvals](https://conecto.chat/docs/approvals.md): calls that wait for a person.
- [The tools directory](https://conecto.chat/tools.md): every tool with its inputs, its price and a real reply.

## More in the docs

- Previous: [Overview](https://conecto.chat/docs.md)
- Next: [Connect your agent](https://conecto.chat/docs/connect.md)
- Every page in one file: https://conecto.chat/docs/all.md
- Every page's title and address: https://conecto.chat/docs/index.json