REST API Reference

The Neverline API is a REST API built on Fastify, served at /v1/.

Authentication

Most endpoints require a Supabase JWT token passed via Authorization: Bearer <token> header, or an API Key via the x-api-key header for programmatic access. Public endpoints (queue join, session polling) do not require authentication.

See Authentication for details.

Organizations

GET /v1/organizations/public/:slug

Get a specific organization profile and its public list of active open queues. This endpoint powers the public directory UI without requiring authentication.

GET /v1/organizations/me

Get the authenticated user's organization details (requires auth).

Queues

GET /v1/queues

List all queues for the authenticated user's organization.

Response:

{
  "queues": [
    {
      "id": "uuid",
      "name": "General Services",
      "status": "open",
      "current_size": 3,
      "total_served": 42,
      "avg_service_time_s": 300
    }
  ]
}

GET /v1/queues/:id

Get a specific queue. Returns real-time current_size by counting actual waiting sessions. Available without authentication (public).

POST /v1/queues

Create a new queue.

Body:

{
  "organizationId": "uuid",
  "name": "New Queue",
  "description": "Optional description"
}

PATCH /v1/queues/:id

Update queue properties (name, status, description, policy settings, etc.).

Queue Alternatives

GET /v1/queues/:id/alternatives

Get the configured alternative queues for a queue (auth required).

POST /v1/queues/:id/alternatives

Add an alternative queue mapping (auth required).

Body:

{
  "alternativeQueueId": "uuid"
}

DELETE /v1/queues/:id/alternatives/:altId

Remove an alternative queue mapping (auth required).

Sessions

POST /v1/sessions/join

Join a queue (public, no auth required).

Body:

{
  "queueId": "uuid",
  "customerName": "Optional Name"
}

Response:

{
  "session": {
    "id": "uuid",
    "position": 5,
    "status": "waiting",
    "customerToken": "unique-token"
  }
}

GET /v1/sessions/:token

Poll session status using customer token (public, no auth). Returns current position, people ahead, estimated wait time, and customer status.

Response:

{
  "session": {
    "id": "uuid",
    "position": 5,
    "status": "waiting",
    "customerStatus": "normal",
    "peopleAhead": 3,
    "estimatedWaitMin": 12
  }
}

POST /v1/sessions/call-next

Call the next customer in a queue (requires auth).

Body:

{
  "queueId": "uuid",
  "staffId": "optional-staff-uuid"
}

POST /v1/sessions/:id/complete

Mark a session as completed (requires auth).

POST /v1/sessions/:id/requeue

Send a customer back to the queue (requires auth).

POST /v1/sessions/:token/away

Set a customer's away status (public, customer token auth).

Body:

{
  "durationMinutes": 20
}

POST /v1/sessions/:token/return

Return a customer from away status (public, customer token auth).

POST /v1/sessions/:token/late

Mark a customer as running late with an ETA (public, customer token auth).

Body:

{
  "etaMinutes": 10
}

GET /v1/queues/:id/sessions

List active sessions for a queue (requires auth). Includes queue estimate data.

Response:

{
  "sessions": [],
  "queueEstimate": {
    "avgServiceMin": 5,
    "activeServers": 2,
    "estimatedWaitForNextMin": 8
  }
}

Announcements

GET /v1/announcements

Fetch active announcements for a scope (public).

Query Parameters:

Param	Required	Description
scopeType	Yes	One of org, location, queue
scopeId	Yes	UUID of the scope entity

POST /v1/announcements

Create an announcement (auth required).

Body:

{
  "scopeType": "queue",
  "scopeId": "uuid",
  "title": "Important Notice",
  "content": "Detailed content...",
  "priority": "info",
  "isPinned": false,
  "startsAt": "2026-01-15T08:00:00Z",
  "endsAt": "2026-01-15T18:00:00Z"
}

PUT /v1/announcements/:id

Update an announcement (auth required). Accepts partial updates.

DELETE /v1/announcements/:id

Delete an announcement (auth required).

Chat

GET /v1/chat/:sessionToken

Get or create a chat thread for a session. Returns thread ID and message history (public, session token auth).

Response:

{
  "threadId": "uuid",
  "messages": [
    {
      "id": "uuid",
      "content": "Hello, how can I help?",
      "senderType": "staff",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ]
}

POST /v1/chat/:sessionToken/messages

Send a message in a chat thread (public, session token auth).

Body:

{
  "content": "I have a question about the wait time"
}

Chat requires chatEnabled: true in the queue's policy settings.

Locations

GET /v1/locations

List all locations for the organization (auth required).

GET /v1/locations/:id

Get location details including active wayfinding overrides (public).

PATCH /v1/locations/:id

Update location navigation fields (auth required). Only whitelisted fields accepted: name, address, instructions, map_url, floor, navigation_notes.

POST /v1/locations/:id/overrides

Create a wayfinding override (auth required).

Body:

{
  "overrideType": "construction",
  "title": "Main entrance closed",
  "description": "Use the side entrance on Elm Street",
  "effectiveFrom": "2026-01-15T00:00:00Z",
  "effectiveUntil": "2026-02-15T00:00:00Z"
}

Planned Arrivals

POST /v1/planned-arrivals

Create a pre-arrival signal (public).

Body:

{
  "organizationId": "uuid",
  "locationId": "uuid",
  "queueId": "uuid",
  "customerName": "Optional",
  "customerPhone": "Optional",
  "plannedDate": "2026-01-20",
  "earliestTime": "09:00",
  "latestTime": "11:00",
  "headcount": 2,
  "confidence": "likely"
}

GET /v1/planned-arrivals/forecast

Get aggregate forecast for a date (auth required).

Query Parameters:

Param	Required	Description
date	Yes	Date in YYYY-MM-DD format

POST /v1/planned-arrivals/:customerToken/convert

Convert a planned arrival into a live queue session (public).

Analytics

GET /v1/analytics/summary

Get analytics summary for an organization.

Query Parameters:

Param	Required	Description
organizationId	Yes	Organization UUID
from	Yes	Start date (YYYY-MM-DD)
to	Yes	End date (YYYY-MM-DD)
queueId	No	Filter to specific queue

Response includes:

• kpis — total served, avg wait time, busiest day, no-shows/abandoned
• dailyTrend — daily counts and averages
• heatmap — hourly visitor volume by day of week
• queueStats — per-queue breakdown
• events — individual session event log

Integrations

GET /v1/api-keys

List all API keys belonging to the authenticated organization.

POST /v1/api-keys

Create a new static HTTP API key. The response will include the raw secret string once, which must be securely stored.

DELETE /v1/api-keys/:id

Revoke an API key permanently.

GET /v1/webhooks

List all registered webhook endpoints for the organization.

POST /v1/webhooks

Register a new webhook URL to receive events.

DELETE /v1/webhooks/:id

Remove an existing webhook endpoint.