Getting started

Quickstart

From nothing to a working call in about five minutes. You need an account and one assistant — if you have been through onboarding, you have both.

For: Someone making their first call
You will need: An account, one assistant, and a terminal
About: 5 minutes end to end

1. Get a key

In the dashboard: Settings → API keys → Create key. Copy it now; it is shown once and stored only as a hash.

terminal

export INTEGRABLE_API_KEY="sk_live_your_key_here"

2. List your assistants

Every other call needs an assistant id, so this is the one to make first.

curl

curl https://api.integrable.cloud/api/bots \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY"

TypeScript

// npm install @integrable-cloud/sdk
import { Integrable } from "@integrable-cloud/sdk";

const client = new Integrable({ apiKey: process.env.INTEGRABLE_API_KEY! });

const { items } = await client.bots.list();
console.log(items.map((b) => `${b.id}  ${b.name}  ${b.status}`).join("\n"));

Python

# pip install integrable-cloud
import os
from integrable_cloud import Integrable

client = Integrable(api_key=os.environ["INTEGRABLE_API_KEY"])

for bot in client.bots.walk():
    print(bot["id"], bot["name"], bot["status"])

Both SDKs handle retries and idempotency keys for you. Neither is required — every call here works with plain curl, which is what the SDKs send underneath.

The same call your website widget makes. It is addressed by the assistant's public key rather than its id, takes no Authorization header, and streams the answer back as Server-Sent Events: start, then meta with the sources it is answering from, then token frames, then done.

curl

curl -N -X POST \
  https://api.integrable.cloud/api/public/widget/$PUBLIC_KEY/chat \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "visitor_id": "quickstart-visitor-1",
    "message": "What are your opening hours?"
  }'

public_key comes from step 2, and visitor_id is any stable string of 8 characters or more that identifies one end user — it is what threads their messages into a single conversation.

The Idempotency-Key is not decoration. This call costs usage credits, so a retry without one asks the model twice, charges twice, and leaves two identical questions in the transcript. See retries.

4. Read what people asked

curl

curl "https://api.integrable.cloud/api/bots/$BOT_ID/conversations?limit=10" \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY"

Follow next_cursor for more rather than incrementing a page number — see pagination.

5. Teach it something

curl

curl -X POST https://api.integrable.cloud/api/bots/$BOT_ID/knowledge \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "raw_text",
    "title": "Opening hours",
    "raw_text": "We are open Monday to Friday, 9am to 5pm, and closed on Sundays."
  }'

source_type is the only required field and decides which of the others apply: raw_text takes raw_text, while url and sitemap take url and fetch the content themselves.

Indexing runs in the background and takes about a minute. Until it reaches ready, the assistant does not know about it yet.

Where to go next

Scope the key down before you ship it. Set up webhooks so you are told when something happens rather than polling for it. Or skip writing code entirely and connect the workspace to Claude.

Something here wrong or missing? Tell us — the documentation and the API are maintained by the same person, so a correction is a fix rather than a ticket.

Quickstart

1. Get a key

2. List your assistants

3. Ask it something

4. Read what people asked

5. Teach it something

Where to go next