DocsQuickstart

Quickstart

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

Someone making their first callNeeds an account, one agent, and a terminal5 minutes end to end

On this page

1. Get a key#

In the agent studio: Developer → 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 agents#

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

curl https://api.integrable.cloud/api/agents \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY"
// 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.agents.list();
console.log(items.map((b) => `${b.id}  ${b.name}  ${b.status}`).join("\n"));
# pip install integrable-cloud
import os
from integrable_cloud import Integrable

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

for agent in client.agents.walk():
    print(agent["id"], agent["name"], agent["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.

3. Ask it something#

The same call your website widget makes. It is addressed by the agent'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/agents/$AGENT_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/agents/$AGENT_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 agent 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 unclear or missing? Tell us and we’ll fix it.