StratusTalk Avion

API documentation

Versioned JSON API for the Avion control plane. The GUI uses same-origin session auth; MCP and external agents will use Bearer tokens (Sanctum personal access tokens) once issued for superadmins.

Base URL & versioning

All endpoints are under /api/v1. Current host: https://avion.stratustalk.com.

GET https://avion.stratustalk.com/api/v1/...

Authentication

Session cookie (Avion GUI — available now)

Log in to Avion in the browser, then call the API with credentials: 'same-origin' so the session cookie is sent. Same-origin only; not for cross-site agents.

Bearer tokens (MCP / external agents — coming soon)

Planned: Laravel Sanctum personal access tokens issued to superadmins. Send Authorization: Bearer <token>. Token issuance UI/API is not shipped in this release; use session auth for GUI integrations today.

Required headers

Header	Value
Accept	application/json (required)
X-XSRF-TOKEN / CSRF	Required for cookie-auth mutations later; not needed for GET reads
Authorization	Bearer … when token auth is available

Rate limits

60 requests per minute per authenticated user (or IP if unauthenticated).

Hostname rules

Path hostnames must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. Shell metacharacters are rejected (422).

Error envelope

Responses use a consistent envelope:

{
  "data": { ... } | null,
  "meta": { ... },
  "error": { "message": "...", "code": "..." } | null
}

Status	Meaning
401	Not authenticated
403	Authenticated but not allowed for this PBX
404	PBX not found (or not visible)
406	Missing Accept: application/json
422	Invalid hostname
503	Live collectors failed (partial DB data may still be in data)

Authorization scopes

• 150 superadmin — all PBXs; secret fields included
• 100 / 50 reseller / technician — PBXs for their reseller
• 10 customer — only their assigned hostname

Non-superadmins do not receive secret fields on PBX or provision records.

Example: GET PBX details

GET /api/v1/pbx/{hostname}
Accept: application/json

Example (browser / same-origin):

fetch('/api/v1/pbx/customer1.example', {
  credentials: 'same-origin',
  headers: { 'Accept': 'application/json' }
}).then(r => r.json())

data shape:

{
  "pbx": { "name", "hostname", "privip", "pop", "secret?", "contactCompany", "contactName", "contactEmail", "contactPhone", "tz" },
  "seats": [ { "ext", "name", "dssgroup", "paginggroup", "directory", "reception", "dss", "sortorder" } ],
  "peers": [ { "peer", "ip", "status" } ],
  "numbers": [ { "did", "forward", "pbx", "state", "comments", "gateway" } ],
  "provision": [ { "mac", "displayname", "sipname", "model", "..." } ],
  "perf": { "uptime", "pod_uptime?", "pod_start_time?", "pod_status?", "alerts", "ifconfig", "routes" },
  "collectors": { "perf": "ok|error", "peers": "ok|error", "k8s": "ok|error|missing|skipped", "messages": [] }
}

Example: PUT PBX details

PUT /api/v1/pbx/{hostname}
Accept: application/json
Content-Type: application/json

Updates contact fields + timezone on pbx, and upserts/deletes seats on extensions (parity with putPBX.php). Soft-removed seats send removed: true (delete by originalExt or ext). Renames delete the old ext then upsert the new one.

// PUT body
{
  "contactCompany": "...",
  "contactName": "...",
  "contactEmail": "...",
  "contactPhone": "...",
  "tz": "America/Chicago",
  "seats": [
    {
      "ext": "101",
      "originalExt": "101",
      "name": "Front Desk",
      "dssgroup": "",
      "paginggroup": "",
      "directory": true,
      "reception": false,
      "dss": false,
      "removed": false
    }
  ]
}

Response data: refreshed pbx contact/tz fields and seats list.

Example: GET / PUT / POST / DELETE number

GET    /api/v1/numbers/{did}
PUT    /api/v1/numbers/{did}
POST   /api/v1/numbers
POST   /api/v1/numbers/{did}/release
DELETE /api/v1/numbers/{did}
Accept: application/json
Content-Type: application/json

GET returns general number fields plus pbx_options (hostnames the actor may assign). PUT updates general fields; ingress gateway is set automatically (border1/CLUSTER for K8S, ast01/OLD otherwise). Rate decks are preserved. POST creates a DID (technician+). Release clears routing fields and sets pbx=AVAILABLE. DELETE removes the row.

// PUT body
{
  "forward": "...",
  "present": "...",
  "sms": "...",
  "pbx": "customer1",
  "comments": "...",
  "state": "ACTIVE"
}

// POST body (create)
{
  "did": "13125551212",
  "forward": "",
  "present": "",
  "sms": "",
  "pbx": "AVAILABLE",
  "comments": ""
}

← Back to login