# AgentLine REST API

Base URL: `https://api.agentline.cloud`. Every authenticated request sends
`Authorization: Bearer $AGENTLINE_API_KEY` and, with a body,
`Content-Type: application/json`. Live contract:
https://api.agentline.cloud/openapi.json

IDs: agents `agt_...`, calls `call_...`, events `evt_...`, turns `turn_...`.
Phone numbers are E.164 (`+1XXXXXXXXXX`).

## Auth

| Method | Path | Auth | Purpose |
|---|---|---|---|
| `POST` | `/v1/auth/otp` | none | `{"email"}`. Emails a code. |
| `POST` | `/v1/auth/verify` | none | `{"email","otp"}`. Returns `api_key` once. |
| `POST` | `/v1/auth/agentid/start` | none | Optional `login_hint`. Returns `authorize_url`, `session_id`. |
| `POST` | `/v1/auth/agentid/poll` | none | `{"session_id"}`. Returns `api_key` once. |
| `GET` | `/v1/auth/keys` | Bearer | List keys. |
| `POST` | `/v1/auth/keys` | Bearer | Mint a key. |
| `DELETE` | `/v1/auth/keys/{key_id}` | Bearer | Revoke a key (not the current one). |

## Agents

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/agents` | List agents. |
| `POST` | `/v1/agents` | Create. `name` required. |
| `GET` | `/v1/agents/{agent_id}` | Get. |
| `PATCH` | `/v1/agents/{agent_id}` | Update sent fields only. |
| `DELETE` | `/v1/agents/{agent_id}` | Delete agent, its calls and messages. |

## Numbers

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/numbers` | List. |
| `POST` | `/v1/numbers` | Buy. `agent_id` required; `country`, `number_type`, `area_code`. |
| `GET` | `/v1/numbers/{number_id}` | Get. |
| `PATCH` | `/v1/numbers/{number_id}/reassign?agent_id=` | Move to another agent. |
| `POST` | `/v1/numbers/attach?phone_number=&agent_id=` | Attach a number bought elsewhere. |
| `POST` | `/v1/numbers/{number_id}/release` | Release. Permanent. |

## Calls

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/calls` | Place a call. `agent_id`, `to_number` required. |
| `GET` | `/v1/calls` | List. `agent_id`, `status`, `limit`, `offset`. |
| `GET` | `/v1/calls/{call_id}` | Status and details. |
| `GET` | `/v1/calls/{call_id}/transcript` | `[{role, text, timestamp}]`. |
| `POST` | `/v1/calls/{call_id}/hangup` | Hang up. |
| `POST` | `/v1/calls/{call_id}/context?turn_id=` | Push live context. Push token or Bearer. |

## Messages

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/messages` | Received texts. `agent_id`, `conversation_id`, `limit`, `offset`. |
| `GET` | `/v1/messages/conversations` | Threads. `agent_id`. |

## Events

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/events` | Poll and consume. `agent_id`, `event_type`, `limit`. |
| `GET` | `/v1/events/peek` | Preview without consuming. `agent_id`, `limit`. |
| `WSS` | `/v1/events/ws?agent_id=&runtime=` | Relay WebSocket. |

## Webhooks

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/webhooks` | List (secrets masked). Optional `agent_id`. |
| `POST` | `/v1/webhooks` | Create or replace. `agent_id`, `url` required. |
| `DELETE` | `/v1/webhooks?agent_id=` | Remove. |
| `POST` | `/v1/webhooks/test?agent_id=` | Send signed `webhook.test`. |

## Voices

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/voices` | Presets. |
| `GET` | `/v1/account/voice` | Account default. |
| `PATCH` | `/v1/account/voice` | Set account default. `{"voice_id"}`. |
| `DELETE` | `/v1/account/voice` | Reset to system default. |

## Billing and Usage

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/billing/balance` | Balance and rate card. |
| `GET` | `/v1/billing/expenditure?period=` | Spend by category. |
| `GET` | `/v1/billing/expenditure/calls` | Per-call charges. |
| `GET` | `/v1/billing/expenditure/numbers` | Per-number charges. |
| `GET` | `/v1/billing/summary?months=` | Monthly totals. |
| `GET` | `/v1/billing/verify/{call_id}` | Check one call's deduction. |
| `GET` | `/v1/usage?period=` | Usage stats. |
| `GET` | `/v1/usage/transactions` | Ledger. |

## Prepaid (No Signup)

| Method | Path | Purpose |
|---|---|---|
| `GET`/`POST` | `/v1/billing/topup/x402/pay?amount=` | Recharge by x402 or MPP. Returns `agent_token`. |
| `POST` | `/v1/x402/numbers/buy` | Buy a number and create its agent. |
| `GET` | `/v1/x402/numbers` | List wallet numbers. |
| `POST` | `/v1/x402/numbers/renew` | Extend lease 30 days. |
| `GET`/`PATCH` | `/v1/x402/agents` | Get or update the agent. |
| `POST` | `/v1/x402/calls` | Place a call. |
| `GET` | `/v1/x402/calls/{call_id}/transcript` | Transcript. |
| `GET`/`POST` | `/v1/x402/webhooks` | Get or set webhook. |
| `POST` | `/v1/x402/webhooks/test` | Test webhook. |
| `GET` | `/v1/x402/events` | Poll events. |

See https://agentline.md/prepaid.md

## Feedback

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/feedback` | Report. `category`, `message` required. |
| `GET` | `/v1/feedback` | Your reports. `category`, `status`, `limit`, `offset`. |

`category`: `bug`, `difficulty`, `feature_request`, `feedback`. Optional
`subject`, `severity` (`low`, `normal`, `high`, `critical`), `agent_id`,
`contact_email`. For bugs, say what you expected and what happened.

```bash
curl -s -X POST https://api.agentline.cloud/v1/feedback \
  -H "Authorization: Bearer $AGENTLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"bug","message":"POST /v1/calls returned 500 for agt_xxx at 14:02 UTC; expected call_id."}'
```

## Errors

| Status | Meaning | Do |
|---|---|---|
| `400` "Agent has no active phone number" | No number on the agent. | Buy one. |
| `401` | Missing or bad key. | Check `AGENTLINE_API_KEY`. |
| `402` `insufficient_balance` | Not enough credit. | Ask the human to top up. |
| `404` on `/v1/auth/agentid/start` | AgentID disabled. | Use OTP. |
| `409` on context push | Turn stale or cancelled. | Stop; discard the result. |
| `410` on context push | Call ended. | Abandon the work. |
| `422` | Validation error; body lists fields. | Fix the request. |
| `429` | Rate limited. | Back off and retry. |

Auth rate limits: 3 OTP per email, 5 OTP per IP, 5 verify per email, per 10
minutes.

## Discovery

- `https://api.agentline.cloud/openapi.json`
- `https://api.agentline.cloud/.well-known/agentline.json`
- `https://api.agentline.cloud/.well-known/agent-payments.json`
- `https://api.agentline.cloud/health`

Support: support@agentline.cloud.

AgentLine: https://agentline.cloud | API: https://api.agentline.cloud | All guides: https://agentline.md