Threll.ai
Guides

Getting Started

Everything you need to make your first authenticated request to the Threll API: an API key, your account ID, and a few minutes.

Prerequisites

Authentication

Every request is authenticated with an API key passed in the x-api-key header. There are no other authentication schemes — no OAuth flows, no session tokens.

Authenticated request
# Store the key in an environment variable, never in source code
export THRELL_API_KEY="your-api-key"

curl https://api.threll.io/v1/accounts/9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b \
  -H "x-api-key: $THRELL_API_KEY"
const BASE = 'https://api.threll.io';

async function threll(path, options = {}) {
  const res = await fetch(BASE + path, {
    ...options,
    headers: {
      'x-api-key': process.env.THRELL_API_KEY,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
  if (!res.ok) throw new Error(`Threll API error ${res.status}`);
  return res.json();
}

const account = await threll('/v1/accounts/9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b');
import os, requests

BASE = "https://api.threll.io"
session = requests.Session()
session.headers["x-api-key"] = os.environ["THRELL_API_KEY"]

account = session.get(f"{BASE}/v1/accounts/9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b").json()

API keys grant full access to your account. Keep them server-side — never embed them in mobile apps, browser code, or version control.

Your first request

Fetch your account to confirm the key works:

GET /v1/accounts/{accountId} — response
{
  "id": "9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "createdAt": "2025-11-02T09:12:44Z",
  "updatedAt": "2026-05-28T16:40:01Z"
}

Then list the workers available on your account. Each worker is a voice agent that can place or receive calls:

List workers
curl https://api.threll.io/v1/accounts/9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b/workers \
  -H "x-api-key: $THRELL_API_KEY"
const workers = await threll('/v1/accounts/9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b/workers');
console.log(workers.map(w => w.name));
// → [ 'Harald', 'Snorre' ]
workers = session.get(f"{BASE}/v1/accounts/9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b/workers").json()
for w in workers:
    print(w["name"])
# Harald
# Snorre

Core concepts

Account
Your organization on Threll. All resources are scoped under /v1/accounts/{accountId}.
Workera.k.a. Threll
A configured voice agent with a name, language, and optional inbound/outbound phone numbers.
Phone call
A single inbound or outbound call handled by a worker. Moves through scheduled → queued → in_progress → completed, then post-processing generates the transcript, dimensions, and next action.
Webhook subscription
An HTTPS endpoint registered to receive call events, account-wide or scoped to a single worker. Each subscription has a signing secret used to verify deliveries.

Next steps

Working with the REST API

Start your first outbound call and read its results.

Read guide →

How Webhooks Work

Receive call events in real time, with verified signatures.

Read guide →
Next: Working with the REST API