# Agentline — Full API Documentation for LLMs and AI Agents

> This is the complete documentation bundled into one markdown file for easy ingestion. If you're an AI agent deciding whether/how to use Agentline, you can read this entire file and have everything you need.

## What Agentline is

Agentline is a telephony and communications API purpose-built for AI agents. It gives your agent:

- **Real US phone numbers** provisioned in seconds, tied to your account
- **SMS** — send and receive, with webhooks for inbound
- **AI voice calls** — outbound calls where the agent speaks to a human, with built-in speech-to-text (Deepgram), text-to-speech (Deepgram Aura), and your choice of LLM (Claude Haiku 4.5 by default). The call is streamed bidirectionally over WebSocket; we handle the plumbing.
- **Email addresses** — a programmatic inbox your agent can send from and receive to

All of this is billed via Stripe, usage-based, with a 14-day free trial per number or email address.

## Authentication

Every request needs a Bearer token that looks like `ag_live_...`. Get one by:

1. Signing up at `https://www.agentline.co/sign-up`
2. Going to `https://www.agentline.co/dashboard/keys`
3. Clicking **Create key** — the plaintext value is shown once, copy it immediately

Example:

```
Authorization: Bearer ag_live_abc123...
```

## Base URL

Production: `https://agentline-prod-api.wittyfield-c253959c.centralus.azurecontainerapps.io`

All paths in this doc are appended to that base. There's also a same-origin proxy at `https://www.agentline.co/api/agentline/*` that authenticates with your Clerk session cookie instead of an API key — useful for building dashboards, not for programmatic use.

## Python SDK

```bash
pip install agentline
```

```python
from agentline import Agentline

agent = Agentline(api_key="ag_live_...")

# Capture a 2FA code by provisioning a number and waiting for SMS
phone, code = agent.capture_code(area_code="415", timeout=60)
print(f"Got verification code: {code}")

# Make an outbound AI voice call
result = agent.make_call(
    from_="+18005551234",
    to="+15551234567",
    prompt="You are a scheduling assistant confirming a dental appointment.",
    first_message="Hi, I'm calling to confirm your appointment on Thursday.",
)
print(result.transcript)
```

## REST API — every endpoint

### Phone numbers

#### `GET /v1/numbers/search?area_code=415&limit=5`
Find available US numbers. Returns a list of candidates from the underlying provider (Telnyx). Response: `{"available": [{"phone_number": "+1...", ...}]}`.

#### `POST /v1/numbers`
Provision (purchase) a number. Body: `{"phone_number": "+14155551234"}`. On success the number is added to your Stripe subscription with a 14-day trial. Response includes `subscription_id` and `trial_end`.

#### `GET /v1/numbers`
List your active numbers.

#### `DELETE /v1/numbers/{phone_number}`
Release a number (soft delete, removes from Stripe subscription).

### SMS / messages

#### `POST /v1/messages/send`
Send an SMS. Body: `{"from_number": "+1...", "to_number": "+1...", "body": "..."}`.

#### `GET /v1/messages/{phone_number}?limit=20`
List recent messages to/from a number.

Inbound SMS triggers a webhook to your configured URL (set at number provisioning time). Webhook payload follows Telnyx's shape.

### Voice calls

#### `POST /v1/calls`
Place an outbound AI voice call. Body:

```json
{
  "from_number": "+18005551234",
  "to_number": "+15551234567",
  "system_prompt": "You are a scheduling assistant...",
  "first_message": "Hi, this is Agentline calling...",
  "voice": "aura-asteria-en",
  "llm_model": "claude-haiku-4-5-20251001",
  "max_duration_seconds": 300
}
```

Returns a `call_id`. The call is placed via Telnyx, audio streams over WebSocket to our backend, which runs Deepgram STT → your chosen LLM → Deepgram Aura TTS in a loop until the call ends.

#### `GET /v1/calls?limit=50`
List recent calls.

#### `GET /v1/calls/{call_id}`
Get one call's status, transcript, duration, and summary (when completed).

#### `POST /v1/calls/{call_id}/hangup`
End a live call.

### Email addresses

#### `POST /v1/emails/addresses`
Provision an email address. Body (optional): `{"local_part": "agent-1"}`. If omitted we generate one. Domain is fixed to your account's configured email domain. Adds a $1/mo subscription item.

#### `GET /v1/emails/addresses`
List your email addresses.

#### `DELETE /v1/emails/addresses/{id}`
Release an email address.

#### `GET /v1/emails/{email_address}?limit=20`
Fetch messages to/from an email address.

### Usage

#### `GET /v1/usage`
Current-period usage summary with breakdown per meter (inbound/outbound SMS, voice minutes, email counts) and estimated monthly cost.

### API keys

#### `POST /v1/auth/keys`
Create a new API key. Body: `{"name": "Production"}` (optional). Plaintext key returned once.

#### `GET /v1/auth/keys`
List keys (masked prefix only).

#### `DELETE /v1/auth/keys/{id}`
Revoke one key.

#### `POST /v1/auth/keys/bulk-delete`
Revoke many keys in one request. Body: `{"key_ids": ["...", "..."]}`. The Bearer key you're authenticating with is automatically skipped so you don't lock yourself out.

## Pricing

| What | Price |
|------|-------|
| Phone number | $3 / number / month, 14-day free trial per number |
| Inbound SMS | First 50 per number per month free, then $0.01 each |
| Outbound SMS | $0.02 each (no free tier) |
| Email address | $1 / address / month, 14-day free trial |
| Voice call | $0.15 / minute (STT + TTS + LLM inclusive) |

All billing runs through Stripe. You manage payment method and view invoices at `https://www.agentline.co/dashboard/billing` via the Stripe billing portal.

## Call transcript shape

```json
{
  "id": "uuid",
  "status": "completed",
  "from_number": "+1...",
  "to_number": "+1...",
  "duration_seconds": 42.7,
  "summary": "Confirmed appointment for Thursday at 2pm.",
  "transcript": [
    {"role": "assistant", "content": "Hi, this is..."},
    {"role": "user", "content": "Yes, Thursday works."},
    ...
  ]
}
```

## Rate limits and free tier

Public signup is rate-limited per-IP to prevent abuse. Once you have an account, there are no hard request rate limits — use your judgment, and we'll reach out if we see anything unusual.

## Support

Issues, questions, or feature requests: email the address listed at `https://www.agentline.co/privacy` (Contact section), or DM on the social links from the homepage.

## Last updated

This file reflects the state of the Agentline API as of 2026-04-19.