AI Studio API

Quickstart in 5 minutes

Make a test key, place a test call, read what happened. A test key never dials anyone and never spends credits, so nothing here can go wrong.

export AISTUDIO_API_KEY=vs_test_...

# JavaScript / TypeScript, Node 18+
npm install https://aistudio.housystan.com/docs/sdk/aistudio-js.tgz
# Python 3.8+
pip install https://aistudio.housystan.com/docs/sdk/aistudio-python.tar.gz

curl https://aistudio.housystan.com/v1/agents -H "x-api-key: $AISTUDIO_API_KEY"
# take an agent "id" from the answer, then:
curl -X POST https://aistudio.housystan.com/v1/calls/outbound -H "x-api-key: $AISTUDIO_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "agent_id": "AGENT_ID", "lead_phone": "+919876543210", "lead_name": "Ravi" }'
# => 201 { "log_id": "...", "status": "initiated", "test": true }

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

const { agents } = await studio.agents.listAgents();
const call = await studio.calls.place({ agentId: agents[0].id, phone: '+919876543210', name: 'Ravi' });
console.log('calling', call.log_id);

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

agents = studio.agents.list_agents()["agents"]
call = studio.calls.place(agent_id=agents[0]["id"], phone="+919876543210", name="Ravi")
print("calling", call["log_id"])

curl https://aistudio.housystan.com/v1/calls/LOG_ID -H "x-api-key: $AISTUDIO_API_KEY"

const done = await studio.calls.waitForEnd(call.log_id);
console.log(done.status, done.summary, done.transcript);

done = studio.calls.wait_for_end(call["log_id"])
print(done["status"], done["summary"])

Common jobs

Copy, paste, replace AGENT_ID. Every example works with a test key first.

curl -X POST https://aistudio.housystan.com/v1/calls/outbound -H "x-api-key: $AISTUDIO_API_KEY" \
  -H "content-type: application/json" -H "Idempotency-Key: order-1042-call" \
  -d '{ "agent_id": "AGENT_ID", "lead_phone": "+919876543210", "lead_name": "Ravi",
        "lead_id": "CRM-42", "dynamic_vars": { "product": "Gold plan" } }'

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

const call = await studio.calls.place({ agentId: AGENT_ID, phone: '+919876543210', name: 'Ravi',
  reference: 'CRM-42', variables: { product: 'Gold plan' } });

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

call = studio.calls.place(agent_id=AGENT_ID, phone="+919876543210", name="Ravi",
                          reference="CRM-42", variables={"product": "Gold plan"})

curl -X POST https://aistudio.housystan.com/v1/calls/outbound -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" \
  -d '{ "agent_id": "AGENT_ID", "lead_phone": "+919876543211", "call_at": "2026-10-21T17:00:00+05:30", "lead_id": "CRM-42" }'
# => 201 { "booking": { "id": "...", "status": "booked", "scheduled_for": "..." } }
curl "https://aistudio.housystan.com/v1/calls/bookings?status=booked" -H "x-api-key: $AISTUDIO_API_KEY"
curl -X DELETE https://aistudio.housystan.com/v1/calls/bookings/BOOKING_ID -H "x-api-key: $AISTUDIO_API_KEY"

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

const { booking } = await studio.calls.book({ agentId: AGENT_ID, phone: '+919876543211',
  at: '2026-10-21T17:00:00+05:30', reference: 'CRM-42' });
await studio.calls.cancelCallBooking({ id: booking.id });

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

booking = studio.calls.book(agent_id=AGENT_ID, phone="+919876543211",
                            at="2026-10-21T17:00:00+05:30", reference="CRM-42")["booking"]
studio.calls.cancel_call_booking(booking["id"])

curl -X POST https://aistudio.housystan.com/v1/campaigns -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" -d '{
  "name": "October offer", "agent_id": "AGENT_ID", "start": true,
  "leads": [ { "phone": "+919876543210", "name": "Ravi", "dynamic_vars": { "city": "Pune" } },
             { "phone": "+919876543211", "name": "Asha" } ] }'
# progress: dialled, answered, interested, still to call
curl https://aistudio.housystan.com/v1/campaigns/CAMPAIGN_ID/stats -H "x-api-key: $AISTUDIO_API_KEY"
# pause / resume
curl -X PATCH https://aistudio.housystan.com/v1/campaigns/CAMPAIGN_ID -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" -d '{ "status": "paused" }'

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

const { campaign } = await studio.campaigns.launch({ name: 'October offer', agentId: AGENT_ID,
  leads: [{ phone: '+919876543210', name: 'Ravi', dynamic_vars: { city: 'Pune' } }] });
const stats = await studio.campaigns.getCampaignStats({ id: campaign.id });
await studio.campaigns.pause(campaign.id);

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

r = studio.campaigns.launch(name="October offer", agent_id=AGENT_ID,
                            leads=[{"phone": "+919876543210", "name": "Ravi", "dynamic_vars": {"city": "Pune"}}])
stats = studio.campaigns.get_campaign_stats(r["campaign"]["id"])
studio.campaigns.pause(r["campaign"]["id"])

curl https://aistudio.housystan.com/v1/calls/LOG_ID -H "x-api-key: $AISTUDIO_API_KEY"
curl "https://aistudio.housystan.com/v1/calls?status=completed&limit=50&offset=0" -H "x-api-key: $AISTUDIO_API_KEY"
curl "https://aistudio.housystan.com/v1/calls?view=log&q=refund&range=30" -H "x-api-key: $AISTUDIO_API_KEY"   # search
curl "https://aistudio.housystan.com/v1/results?since=2026-10-01T00:00:00Z" -H "x-api-key: $AISTUDIO_API_KEY"  # then ?cursor=next_cursor

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

const { call } = await studio.calls.getCall({ id: LOG_ID });
for await (const c of studio.paginate('listCalls', { status: 'completed' })) console.log(c.id, c.status);
const found = await studio.calls.listCalls({ view: 'log', q: 'refund', range: '30' });
for await (const r of studio.paginate('listResults', { since: '2026-10-01T00:00:00Z' })) console.log(r.outcome, r.collected);

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

call = studio.calls.get_call(LOG_ID)["call"]
for c in studio.paginate("listCalls", status="completed"):
    print(c["id"], c["status"])
found = studio.calls.list_calls(view="log", q="refund", range="30")
for r in studio.paginate("listResults", since="2026-10-01T00:00:00Z"):
    print(r["outcome"], r["collected"])

curl -X PUT https://aistudio.housystan.com/v1/settings/webhooks -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" -d '{
  "post_call": { "url": "https://your-app.example.com/aistudio/webhook", "secret": "a-long-random-string", "enabled": true } }'
# a signed sample of any event:
curl -X POST https://aistudio.housystan.com/v1/settings/webhooks/test -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" -d '{ "event": "lead.interested" }'

import express from 'express';
import { verifyWebhook } from '@housystan/aistudio';

const app = express();
app.post('/aistudio/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try { event = verifyWebhook(req.body, req.headers, process.env.AISTUDIO_WEBHOOK_SECRET); }
  catch { return res.sendStatus(400); }
  if (event.event === 'lead.interested') console.log('interested:', event.lead_name, event.lead_phone);
  if (event.event === 'visit.booked') console.log('visit at', event.visit.at);
  res.sendStatus(200);
});
app.listen(3000);

from fastapi import FastAPI, HTTPException, Request
from aistudio import verify_webhook, WebhookVerificationError

app = FastAPI()

@app.post("/aistudio/webhook")
async def aistudio_webhook(request: Request):
    try:
        event = verify_webhook(await request.body(), request.headers, SECRET)
    except WebhookVerificationError:
        raise HTTPException(400)
    if event["event"] == "lead.interested":
        print("interested:", event["lead_name"], event["lead_phone"])
    return {"ok": True}

curl -X POST https://aistudio.housystan.com/v1/voices/tts -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" \
  -d '{ "text": "Welcome! Today everything is ten percent off.", "format": "mp3" }' -o voice-over.mp3

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

import { writeFileSync } from 'node:fs';

const audio = await studio.voices.voiceOver({ text: 'Welcome! Today everything is ten percent off.' });
writeFileSync('voice-over.mp3', audio.data);

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

studio.voices.voice_over("Welcome! Today everything is ten percent off.").save("voice-over.mp3")

curl https://aistudio.housystan.com/v1/credits -H "x-api-key: $AISTUDIO_API_KEY"
# => { "credits": 97600, "balance_inr": 9760, "plan": { "name": "...", "ai_inr_per_minute": ..., ... } }
curl "https://aistudio.housystan.com/v1/credits/ledger?limit=50" -H "x-api-key: $AISTUDIO_API_KEY"   # every charge, newest first

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

const { credits } = await studio.credits.get();
for await (const line of studio.paginate('getCreditsLedger', { limit: 100 })) console.log(line.at, line.credits, line.note);

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

print(studio.credits.get()["credits"])
for line in studio.paginate("getCreditsLedger", limit=100):
    print(line["at"], line["credits"], line["note"])

Test mode

A key that starts vs_test_ is a test key. It uses the same URLs and sees your real workspace (agents, voices, campaigns and calls to read), but it can never dial anyone and never spend a credit. Make one on the Developers page (kind: Test key); test keys work on every plan, so you can build before you buy.

What a test key does

Choose the outcome with the last digit of the number

A call's status (GET /calls) is one of ringing, in-progress, completed, failed, no-answer (hyphen); the status in a webhook is one of completed, no_answer, busy, voicemail, failed (underscore). Test and live use the same words.

Every answer carries the header X-Test-Mode: true and "test": true; every webhook body carries "test": true. Test webhooks are signed like real ones, sent once and never retried. Idempotency-Key works as in live mode. Test objects are kept for 30 days.

Send us your leads (and have them called at once)

Every lead you send is on the Leads page at once, with its source, and the call result, next call and appointment follow as for any lead. Two ways in: a lead URL (Settings › Lead sources: a secret address per source for a website form, Google Ads, Zapier / Make or a portal; no key needed) and POST /v1/leads with an API key.

call: "now" = the call is due 5 seconds after the lead arrives (in calling hours it rings within seconds; outside them at the next opening, never at night), "schedule" + call_at = at that time, "no" = only saved. Without call the workspace's API rule decides. Every call goes through your normal calling: the do-not-call list, the wallet (an empty wallet = the lead is kept and shown under Needs you, and called the moment money is added), your lines (all busy = it waits its turn, first come first called).

Identity: the same external_id (or Idempotency-Key header) twice is the SAME lead (200, "replayed": true), nothing booked twice. Never the phone: the same number again within 10 minutes is a new lead flagged as a duplicate and not called a second time. Every other field is kept as one of the lead's columns and the agent can use it as {{city}}. Webhooks: call.ended for each call, lead.created when a call finds interest (with your lead_id = the external id).

curl -X POST https://aistudio.housystan.com/v1/leads -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" \
  -d '{ "name": "Ravi", "phone": "+919876543210", "email": "ravi@example.com", "external_id": "crm-5821",
        "fields": { "car_model": "Creta", "city": "Pune" }, "call": "now", "agent_id": "<agent id>" }'
# 201 { "lead": { "id": "...", "ref": 1042, "call": { "state": "calling_soon", "label": "Calling now" } },
#       "call": { "decision": "calling", "scheduled_for": "...", "due_in_ms": 5012, "waiting_for_line": false } }

curl https://aistudio.housystan.com/v1/leads/<id> -H "x-api-key: $AISTUDIO_API_KEY"   # status, the call now, calls made, appointment

# a lead URL (no key; the token is the key) - e.g. from a website form or Zapier
curl -X POST https://aistudio.housystan.com/in/ls_xxxxxxxx -H "content-type: application/json" -d '{ "name": "Asha", "phone": "9876543210", "city": "Pune" }'
# add ?test=1 to try it: read and answered, nothing saved or called

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

const { lead, call } = await studio.leads.createLead({
  name: 'Ravi', phone: '+919876543210', external_id: 'crm-5821',
  fields: { car_model: 'Creta' }, call: 'now', agent_id: AGENT_ID,
});
console.log(lead.ref, call.label);

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

r = studio.leads.create_lead(name="Ravi", phone="+919876543210", external_id="crm-5821",
                             fields={"car_model": "Creta"}, call="now", agent_id=AGENT_ID)
print(r["lead"]["ref"], r["call"]["label"])

Google Ads lead forms: Lead delivery › Webhook: the lead URL as the URL, the token (after /in/) as the key; "Send test data" is answered and never saved. Facebook / Instagram Lead Ads: today through Zapier or Make (Facebook Lead Ads › New Lead, then POST to the lead URL or our app's Create Lead action). IndiaMART, JustDial, 99acres, MagicBricks, Housing: ask them to push new enquiries to the lead URL; their usual field names (SENDER_MOBILE, mobile, leadid ...) are read as they come. A test key (vs_test_) answers POST /v1/leads with what would happen; nothing is saved or called.

Your own variables

Write {{any_name}} in an agent's prompt, first message, knowledge base (always-known facts and documents), a tool's URL / headers / fixed fields, or a WhatsApp template blank. It is filled on every call, like ElevenLabs' dynamic variables. Each name takes the first value it finds, in this order:

1. The call request: dynamic_variables (or dynamic_vars) on POST /v1/calls/outbound, the Test call form, MCP variables.
2. The lead: every column of its uploaded list or Google Sheet (a column treatment fills {{treatment}}).
3. Your workspace default: Settings, Variables, or PUT /v1/settings/variables.
4. What the Studio knows: business_name, agent_name, lead_name, lead_phone_masked, today, current_date, current_time, current_datetime, tomorrow_date, appointment_time, appointment_date, appointment_type, last_call_summary.

The phone engine adds greeting_prefix (the first name, when the name is a person's) and system__caller_id, system__time_ist and the other system__ names.

A name nothing fills is never spoken: it is removed and the sentence closes up ("Hello {{lead_name}}, ..." becomes "Hello, ..."), the call records it, and the agent editor shows it in red. Give a name that may be missing a default.

# a default for every call of the workspace
curl -X PUT https://aistudio.housystan.com/v1/settings/variables -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" \
  -d '{ "variables": [ { "name": "clinic_city", "default_value": "Pune" }, { "name": "offer", "default_value": "a free check-up" } ] }'

# this call's own values win over the lead's columns and the defaults
curl -X POST https://aistudio.housystan.com/v1/calls/outbound -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" \
  -d '{ "agent_id": "AGENT_ID", "lead_phone": "+919876543210", "lead_name": "Priya",
        "dynamic_variables": { "treatment": "root canal" } }'
# with a test key the answer shows "variables" (each value and where it came from) and the "first_message"

import { AIStudio } from '@housystan/aistudio';
const studio = new AIStudio(); // reads AISTUDIO_API_KEY

await studio.settings.replaceWorkspaceVariables({ variables: [{ name: 'clinic_city', default_value: 'Pune' }] });
const call = await studio.calls.place({ agentId: AGENT_ID, phone: '+919876543210', name: 'Priya',
  variables: { treatment: 'root canal' } });

from aistudio import AIStudio
studio = AIStudio()  # reads AISTUDIO_API_KEY

studio.settings.replace_workspace_variables(variables=[{"name": "clinic_city", "default_value": "Pune"}])
call = studio.calls.place(agent_id=AGENT_ID, phone="+919876543210", name="Priya",
                          variables={"treatment": "root canal"})

A first message Hi {{lead_name}}, about your {{treatment}} at our {{clinic_city}} clinic then says "Hi Priya, about your root canal at our Pune clinic". Check an agent without calling: POST /v1/settings/variables/preview, or GET /v1/agents/{id}/variables (every name it uses, who fills it, and those missing on real calls).

Send to my system: webhooks, Zapier, Make, your CRM

In the Studio: Send to my system. Pick one: the Studio is your CRM (nothing is sent), your own system (a webhook), Zapier or Make, LeadSquared, Zoho CRM, or my CRM does it (your CRM books the call-backs and sends the messages; we only send it the events). The same on every plan.

Every post is signed: X-Webhook-Signature: sha256=HMAC_SHA256(secret, X-Webhook-Timestamp + "." + raw_body); X-Webhook-Id is the event_id (dedupe on it). Answer 2xx; anything else is retried with backoff for about 17 minutes, and every delivery is listed on the page and at GET /v1/settings/webhooks/deliveries. Receivers that asked for the older names lead.interested, visit.booked or callback.booked keep getting them.

curl -X PUT https://aistudio.housystan.com/v1/settings/webhooks -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" \
  -d '{ "post_call": { "url": "https://crm.example.com/ai-studio", "secret": "a-long-random-secret-1234", "enabled": true,
        "events": ["call.ended", "lead.created", "lead.updated", "appointment.booked"] } }'
curl -X POST https://aistudio.housystan.com/v1/settings/webhooks/test -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" -d '{ "event": "lead.created" }'

# Zapier / Make: subscribe a hook URL to one event, then send it a sample
curl -X POST https://aistudio.housystan.com/v1/hooks -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" \
  -d '{ "target_url": "https://hooks.zapier.com/hooks/catch/1/abc/", "event": "lead.created", "source": "zapier" }'
curl -X POST https://aistudio.housystan.com/v1/hooks/HOOK_ID/test -H "x-api-key: $AISTUDIO_API_KEY"

# "my CRM does it": your CRM books the call-backs and sends the messages
curl -X PUT https://aistudio.housystan.com/v1/settings/send-to -H "x-api-key: $AISTUDIO_API_KEY" -H "content-type: application/json" -d '{ "mode": "crm" }'

// check a post really came from us (Node)
import { createHmac, timingSafeEqual } from 'node:crypto';
const ts = req.headers['x-webhook-timestamp'], sig = String(req.headers['x-webhook-signature']);
const want = 'sha256=' + createHmac('sha256', SECRET).update(ts + '.' + rawBody).digest('hex');
const ok = sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want))
  && Math.abs(Date.now() / 1000 - Number(ts)) < 300;

# check a post really came from us (Python)
import hmac, hashlib, time
ts, sig = headers["X-Webhook-Timestamp"], headers["X-Webhook-Signature"]
want = "sha256=" + hmac.new(SECRET.encode(), (ts + "." + raw_body).encode(), hashlib.sha256).hexdigest()
ok = hmac.compare_digest(sig, want) and abs(time.time() - int(ts)) < 300

Connect your CRM

In the Studio: Integrations, Your CRM. Or with a key holding settings:write. We then POST interested leads and call results to your URL, each one signed with your workspace secret (the same secret as the post-call webhook). Every request names its action; answer 2xx with JSON, and {} to any action you do not use.

curl -X PUT https://aistudio.housystan.com/v1/settings/crm -H "x-api-key: $KEY" -H "content-type: application/json" -d '{ "url": "https://crm.yourcompany.com/ai-studio" }'
# => { "crm": { "type": "webhook", "url": "...", "secret_set": true }, "secret": "whsec_..." }   (the secret only when one was just made: copy it)
curl -X POST https://aistudio.housystan.com/v1/settings/crm/test -H "x-api-key: $KEY"        # one signed sample, "test": true; shows your answer
curl -X POST https://aistudio.housystan.com/v1/settings/crm/secret -H "x-api-key: $KEY"      # a new secret, shown once
curl -X PUT https://aistudio.housystan.com/v1/settings/crm -H "x-api-key: $KEY" -H "content-type: application/json" -d '{ "enabled": false }'

# What arrives (POST, JSON). Headers: x-voice-studio-action, x-voice-studio-timestamp, x-voice-studio-signature ("sha256=<hex>")
# { "id": "...", "ts": 1789000000, "org_id": "...", "action": "promote_ai_lead", "payload": { "leadName": "Rajesh", "leadPhone": "...", ... } }
#   expected = "sha256=" + HMAC_SHA256(secret, ts + "." + raw_body).hex()   - reject if older than 300 s.
# Answer { "crm_lead_id": "<your id>" } to promote_ai_lead so the call is linked to your lead.

Libraries

Official clients for JavaScript/TypeScript (Node 18+) and Python (3.8+), no dependencies. Every operation in the reference below is a typed method (generated from the OpenAPI file), plus: your key from AISTUDIO_API_KEY, retries with backoff (rate limits wait for Retry-After; a call is never resent unless it is safe), an Idempotency-Key on every create, pagination, typed errors with status and code, and webhook verification.

# no library: every example on this page has a curl tab
curl https://aistudio.housystan.com/v1/agents -H "x-api-key: $AISTUDIO_API_KEY"

npm install https://aistudio.housystan.com/docs/sdk/aistudio-js.tgz
# then: import { AIStudio } from '@housystan/aistudio';

pip install https://aistudio.housystan.com/docs/sdk/aistudio-python.tar.gz
# then: from aistudio import AIStudio

Everything the libraries do, with examples: Libraries guide. Postman: aistudio.postman_collection.json (set the apiKey variable). The machine-readable spec: /docs/openapi.yaml.

AI assistants (MCP)

Claude, ChatGPT, Cursor and any assistant that speaks MCP can use your workspace with an API key: list agents, read calls and campaigns, search conversations, check the wallet, and, when you allow it, place or book calls and make voice-overs. Everything runs as your key: its scopes, your wallet, calling hours and do-not-call list. A test key simulates every call.

Read-only by default. Tools that change anything appear only on https://aistudio.housystan.com/mcp?writes=1 (or aistudio-mcp --allow-writes). Price first: a tool that costs money answers with the price and does nothing; the assistant has to ask you and call it again with confirm: true.

Remote server (nothing to install)

URL     https://aistudio.housystan.com/mcp            (Streamable HTTP)
Header  Authorization: Bearer vs_live_...   (or vs_test_...)

# Claude Code
claude mcp add --transport http aistudio https://aistudio.housystan.com/mcp --header "Authorization: Bearer $AISTUDIO_API_KEY"

# Cursor: ~/.cursor/mcp.json
{ "mcpServers": { "aistudio": { "url": "https://aistudio.housystan.com/mcp", "headers": { "Authorization": "Bearer vs_live_..." } } } }

Local server (Claude Desktop and other apps that start a command)

{
  "mcpServers": {
    "aistudio": {
      "command": "npx",
      "args": ["-y", "https://aistudio.housystan.com/docs/sdk/aistudio-mcp.tgz"],
      "env": { "AISTUDIO_API_KEY": "vs_live_..." }
    }
  }
}

# add "--allow-writes" to args to allow calls and voice-overs

Tools

Website widget

Put an agent on any website with one line: visitors talk to it out loud or type. In the Studio, Web widget: pick the agent, add the websites allowed to show it (the widget opens only there), choose the look; the Developers page shows your line and a live preview.

<script src="https://aistudio.housystan.com/embed.js" data-org="YOUR_WORKSPACE_ID" async></script>

Optional, per page: data-color="#0f766e" data-position="left" data-mode="chat" (voice, chat or both) data-title data-subtitle data-open="1". Your own button: VoiceStudioWidget.start(). Each typed reply and each 15 seconds of voice is charged at your AI rate; with an empty wallet the widget does not open.

Authentication

Send your key in the x-api-key header on every request.

curl https://aistudio.housystan.com/v1/calls \
  -H "x-api-key: vs_live_xxxxxxxxxxxxxxxx"

Studio sessions use Authorization: Bearer <jwt> instead. Sessions are unscoped and are governed by the signed-in user’s role; use a managed key for server-to-server work.

The legacy account-wide organisation key is not accepted on /v1. It is one un-scopable, un-rotatable string per account, so it cannot be the credential a public API is built on. Sending it returns 401 legacy_key_not_allowed_on_v1. Existing integrations on the unversioned /api paths are unaffected.

Every request is scoped to the organisation the credential belongs to. There is no org_id parameter anywhere in this API, and sending one changes nothing: a key can never read another organisation’s agents, calls, leads or recordings. An id that belongs to someone else returns 404 — never 403, which would confirm it exists.

Scopes

A key carries scopes. * satisfies everything; a bare resource scope covers its verbs, so calls grants both calls:read and calls:write. Reads need the :read scope, writes the :write one. A key created without an explicit scopes array gets ["*"].

A few pairings are worth stating outright:

• /v1/agents — Versions, rollback, analysis config and languages are all agent reads/writes: a rollback replaces the live agent.
• /v1/voices — The voice catalogue is read with agents:read.
• /v1/subjects — What a campaign is about (your projects, courses...): picked when configuring one.
• /v1/llm — The priced model catalogue an agent picks from.
• /v1/clips — An IVR clip is agent content.
• /v1/appointments — Site visits / meetings / demos (migration 322): appointments:write books, confirms, moves and cancels; the same state machine as a graded call.
• /v1/results — What our calls produced, pulled by the customer on their own schedule. Read with calls:read - it is the outcome of a call, and a key that may read calls may read what they achieved.
• /v1/calls — calls:write is what places a call (POST /v1/calls/outbound). Give it out deliberately.
• /v1/recordings — Separate from calls:read so an integrator can read call metadata without the audio.
• /v1/dnd — The do-not-call list gates dialling, so it rides with the calls scopes.
• /v1/hooks — REST hooks (Zapier, Make): call results as they happen. Subscribing is calls:write; the recent-items list is calls:read.
• /v1/me — Who am I - the auth test of the Zapier / Make apps. Read with calls:read.
• /v1/leads — Leads you send in (and call now / schedule / not): sending one is calls:write, reading them calls:read.
• /v1/dtmf-report — Keypad responses are campaign output.
• /v1/dids — DIDs are the phone numbers. numbers:write can rotate a campaign onto fresh numbers.
• /v1/carriers — The workspace's own calling provider (Twilio / SIP) and its imported numbers; off until the platform switches it on.
• /v1/tools — The org tool library — webhook and transfer-to-number tools an agent may call.
• /v1/billing — Plan, this month’s billed usage and invoices. Read-only by design — plans are assigned by the platform.
• /v1/api-keys — keys:read lists prefixes and scopes only — the secret is never returned by anything. keys:write creates, rotates and revokes.
• /v1/settings — Holds provider keys. Never grant settings:* to a third-party integration.
• /v1/settings/webhooks — Delivery URL for call outcomes. Mounted before /v1/settings, so it needs its own row.
• /v1/settings/crm — The workspace’s own CRM connection (URL, signing secret, test). Mounted before /v1/settings, so it needs its own row.
• /v1/settings/business — What the workspace sells, in its own words (P1: the call judge and the appointment hours read it). Mounted before /v1/settings.
• /v1/settings/send-to — Where call results go (none / webhook / Zapier-Make / LeadSquared / Zoho / "my CRM does it"). Mounted before /v1/settings, so it needs its own row.
• /v1/settings/variables — Workspace {{variables}} and their default values (call request > lead field > workspace default > system). Mounted before /v1/settings.
• /v1/languages — Speech-language catalogue, read with agents:read like /v1/voices.
• /v1/secrets — Provider keys live here, so it rides with settings. Never grant settings:* to a third party.
• /v1/analytics — Aggregates over the account, read with usage:read.
• /v1/trunks — Platform admin only — carrier trunk capacity.
• /v1/system — GET /v1/system/pause (system:read) works for every account; everything else here, system:write included, is platform admin only.

Refused requests answer 403 naming both the scope required and the scopes granted, so the fix never needs a support ticket.

Errors

Every error is JSON and always carries error, a sentence you can act on. Failures you should branch on also carry a stable code.

Rate limits

Per organisation, per minute — 600 by default. Over the limit you get an honest 429 with a Retry-After header rather than a dropped request. Studio traffic and API traffic count in separate buckets, so a campaign cannot rate-limit an operator out of their own dashboard.

{
  "error": "Rate limit exceeded",
  "retry_after_seconds": 12,
  "limit_per_minute": 600
}