API Quickstart

Make your first Voice AI call with the Agentic OS API — verify your key, get an agent, place a call, and fetch the transcript in about five minutes. Go from an API key to a real phone call (with a transcript and recording) in four steps. Every request below uses the production base URL https://api.agentic-os.com and Bearer authentication.

Don’t have a key yet? Follow Generate an API key first, then come back here. Telephone calls consume wallet credits, so keep a test number handy.

Prerequisites

An Agentic OS API key ( Authorization: Bearer <key> )
A recipient phone number in E.164 format, e.g. +919876543210
curl, or Python 3, or Node 18+

Set your key as an environment variable so it’s not pasted into every command:

export AGENTIC_OS_API_KEY="ao-xxxxxxxxxxxxxxxx"

Verify your API key

A quick read-only call confirms the key works and shows your wallet balance and concurrency limit before you spend any credits.

curl https://api.agentic-os.com/api/v1/billing/wallet \
  -H "Authorization: Bearer $AGENTIC_OS_API_KEY"

import os, requests

resp = requests.get(
    "https://api.agentic-os.com/api/v1/billing/wallet",
    headers={"Authorization": f"Bearer {os.environ['AGENTIC_OS_API_KEY']}"},
)
print(resp.json())

const resp = await fetch("https://api.agentic-os.com/api/v1/billing/wallet", {
  headers: { Authorization: `Bearer ${process.env.AGENTIC_OS_API_KEY}` },
});
console.log(await resp.json());

A 200 response with a balance field means the key is valid.

Get or create an agent

Use an existing agent, or create one from a persona.

curl -X POST https://api.agentic-os.com/api/v1/agents \
  -H "Authorization: Bearer $AGENTIC_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quickstart Agent",
    "agent_persona_id": "PERSONA_ID",
    "is_active": true
  }'

resp = requests.post(
    "https://api.agentic-os.com/api/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['AGENTIC_OS_API_KEY']}"},
    json={
        "name": "Quickstart Agent",
        "agent_persona_id": "PERSONA_ID",
        "is_active": True,
    },
)
agent = resp.json()
print(agent["id"])

const resp = await fetch("https://api.agentic-os.com/api/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AGENTIC_OS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Quickstart Agent",
    agent_persona_id: "PERSONA_ID",
    is_active: true,
  }),
});
const agent = await resp.json();
console.log(agent.id);

Need a persona ID? List them first with GET /prompts/personas. Save the returned agent id — you’ll pass it as agentId in the next step.

Calls go out through a voice number already registered to your tenant, not a raw phone string:

curl https://api.agentic-os.com/api/v1/voice-numbers \
  -H "Authorization: Bearer $AGENTIC_OS_API_KEY"

Save one entry’s id as voiceNumberId. See Purchase Phone Numbers if you don’t have one yet.

Place a call

curl -X POST https://api.agentic-os.com/api/v1/channels/voice/call \
  -H "Authorization: Bearer $AGENTIC_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_ID",
    "voiceNumberId": "YOUR_VOICE_NUMBER_ID",
    "toNumber": "+919876543210"
  }'

resp = requests.post(
    "https://api.agentic-os.com/api/v1/channels/voice/call",
    headers={"Authorization": f"Bearer {os.environ['AGENTIC_OS_API_KEY']}"},
    json={
        "agentId": "YOUR_AGENT_ID",
        "voiceNumberId": "YOUR_VOICE_NUMBER_ID",
        "toNumber": "+919876543210",
    },
)
call = resp.json()
print(call["sessionId"])

const resp = await fetch("https://api.agentic-os.com/api/v1/channels/voice/call", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AGENTIC_OS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "YOUR_AGENT_ID",
    voiceNumberId: "YOUR_VOICE_NUMBER_ID",
    toNumber: "+919876543210",
  }),
});
const call = await resp.json();
console.log(call.sessionId);

The response returns immediately with status: "QUEUED" and a sessionId — the call itself happens asynchronously.

Fetch the transcript

Poll the call detail endpoint once the call has ended.

curl https://api.agentic-os.com/api/v1/call-logs/YOUR_SESSION_ID/full \
  -H "Authorization: Bearer $AGENTIC_OS_API_KEY"

resp = requests.get(
    f"https://api.agentic-os.com/api/v1/call-logs/{session_id}/full",
    headers={"Authorization": f"Bearer {os.environ['AGENTIC_OS_API_KEY']}"},
)
print(resp.json()["transcript"])

const resp = await fetch(
  `https://api.agentic-os.com/api/v1/call-logs/${sessionId}/full`,
  { headers: { Authorization: `Bearer ${process.env.AGENTIC_OS_API_KEY}` } },
);
const { transcript, recording } = await resp.json();
console.log(transcript, recording);

The response includes the full turn-by-turn transcript, a recording URL, and post-call analytics (sentiment, intent, summary).

Alternative: receive results via webhook

Instead of polling, register a webhook URL on the agent and Agentic OS will POST the call summary and recording link to it as soon as the call ends. See webhooks.

Run the whole flow as one script

#!/usr/bin/env bash
set -euo pipefail

BASE="https://api.agentic-os.com/api/v1"
AUTH="Authorization: Bearer $AGENTIC_OS_API_KEY"

PERSONA_ID=$(curl -s "$BASE/prompts/personas" -H "$AUTH" | jq -r '.[0].id')

AGENT_ID=$(curl -s -X POST "$BASE/agents" -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"name\":\"Quickstart Agent\",\"agent_persona_id\":\"$PERSONA_ID\",\"is_active\":true}" \
  | jq -r '.id')

VOICE_NUMBER_ID=$(curl -s "$BASE/voice-numbers" -H "$AUTH" | jq -r '.[0].id')

SESSION_ID=$(curl -s -X POST "$BASE/channels/voice/call" -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"agentId\":\"$AGENT_ID\",\"voiceNumberId\":\"$VOICE_NUMBER_ID\",\"toNumber\":\"+919876543210\"}" \
  | jq -r '.sessionId')

echo "Call queued: $SESSION_ID"

Next steps

Inbound Quickstart

Configure a number to receive calls.

Batch Calling Quickstart

Call thousands of contacts at once.

Agent Setup

Tune LLM, voice, and call behavior.

API Reference

Full endpoint documentation.

Overview & Evaluation

Platform Features

Concepts

Build & Configure Agents

API Quickstart

Prerequisites

Alternative: receive results via webhook

Run the whole flow as one script

Next steps

Inbound Quickstart

Batch Calling Quickstart

Agent Setup

API Reference

​Prerequisites

​Alternative: receive results via webhook

​Run the whole flow as one script

​Next steps

Inbound Quickstart

Batch Calling Quickstart

Agent Setup

API Reference

Prerequisites

Alternative: receive results via webhook

Run the whole flow as one script

Next steps