Developer API
API Reference
Everything you need to build queue infrastructure in an afternoon. Base URL: https://api.linie.io/v1
Quick start
From zero to a live queue in four steps.
Get an API key
Sign up for a free hobby tier — no credit card needed. Your key appears in the dashboard under Account → API Keys.
Create a queue
POST to /queues with your TTL, heartbeat interval, and reminder thresholds.
const queue = await linie.queues.create({
ttl: 600,
heartbeat_interval: 60,
reminder_at: [0.5, 0.8, 1.0],
});queue = client.queues.create(
ttl=600,
heartbeat_interval=60,
reminder_at=[0.5, 0.8, 1.0],
)curl -X POST https://api.linie.io/v1/queues \
-H "Authorization: Bearer $LINIE_KEY" \
-H "Content-Type: application/json" \
-d '{"ttl":600,"heartbeat_interval":60,"reminder_at":[0.5,0.8,1.0]}'Enqueue a customer
Call POST /queues/{id}/enqueue with optional priority and metadata.
const entry = await linie.queues.enqueue(queue.id, {
priority: 0,
metadata: { phone: "+6591234567", name: "Ahmad R." },
});entry = client.queues.enqueue(queue.id,
priority=0,
metadata={"phone": "+6591234567", "name": "Ahmad R."},
)curl -X POST https://api.linie.io/v1/queues/$QUEUE_ID/enqueue \
-H "Authorization: Bearer $LINIE_KEY" \
-H "Content-Type: application/json" \
-d '{"priority":0,"metadata":{"phone":"+6591234567"}}'Receive webhooks
Configure a webhook URL on your queue. Linie fires position_changed, your_turn, and expired events to your endpoint.
Authentication
All API requests require a Bearer token in the Authorization header.
Authorization: Bearer linie_live_<your-key>Manage keys at Account → API Keys. Only the SHA-256 hash of your key is stored — if you lose it, rotate it.
Endpoints
Queues
| Method | Path | Description |
|---|---|---|
POST | /queues | Create a queue |
GET | /queues/{id} | Get a queue |
DELETE | /queues/{id} | Delete (async drain, returns 202) |
GET | /queues | List queues (paginated) |
PATCH | /queues/{id} | Configure WhatsApp notifications |
Entries
| Method | Path | Description |
|---|---|---|
POST | /queues/{id}/enqueue | Add an entry |
GET | /queues/{id}/next | Peek at head (204 if empty) |
POST | /queues/{id}/dequeue | Remove and return head |
GET | /queues/{id}/entries/{entry_id} | Get an entry |
POST | /queues/{id}/entries/{entry_id}/heartbeat | Reset TTL countdown |
POST | /queues/{id}/entries/{entry_id}/set_priority | Update priority |
DELETE | /queues/{id}/entries/{entry_id} | Remove explicitly |
Analytics Growth+
| Method | Path | Description |
|---|---|---|
GET | /queues/{id}/analytics | Wait time, abandonment rate, throughput |
Error codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_config | Queue config validation failed |
| 400 | invalid_priority | Priority out of range |
| 400 | missing_webhook_url | on_events set but no URL |
| 401 | unauthorized | Missing or invalid API key |
| 402 | tier_limit_reached | Queue or operation limit for your tier |
| 404 | queue_not_found | No queue with that ID |
| 404 | entry_not_found | No entry with that ID |
| 409 | duplicate_entry | Idempotency key already used — re-fetch the existing entry with GET /entries/{entry_id} |
| 409 | queue_empty | Dequeue on an empty queue |
| 429 | rate_limited | Request rate exceeded for your tier |
| 500 | internal_error | Server error — retry with backoff |
Rate limits
| Tier | Operations included | Max req/s |
|---|---|---|
| Hobby | 1,000 / day | 10 |
| Starter | 500,000 / month | 50 |
| Growth | 5,000,000 / month | 200 |
| Scale | 20,000,000 / month | 1,000 |
| Enterprise | Custom | Custom |
Operations: enqueue, dequeue, peek, heartbeat, set_priority. Exceeding the daily/monthly window returns 402 tier_limit_reached; exceeding req/s returns 429 rate_limited with a Retry-After: 1 header.
SDKs
Official open-source SDKs wrap the REST API with typed clients.