API

Every service has a JSON API at https://<service>.xvii.network/api/v1, the same one its panel and the CLI use. Each service's page lists what it offers; this page covers what they have in common.

Authentication

curl -H "Authorization: Bearer $XVII_TOKEN" https://pages.xvii.network/api/v1/deploys

Credential	Use
API token `xv_…`	scripts and CI; create with `xvii tokens create`
access token (JWT)	what the CLI and panels get from id; 15 minutes
panel session cookie	browsers only; requests must be same-origin
CI job token	exchanged at id through a trust rule (`POST https://id.xvii.network/oauth/token`, token exchange)

A token's scope (read, deploy, write) and its team roles decide what it may do. Requests with a cookie are refused when Sec-Fetch-Site or Origin says they come from another site.

Team context

Where a resource is created, say which team with the X-Xvii-Team: <team id> header or ?team=. Lists show what the caller may see across teams unless narrowed.

Errors

A status code and a body:

{
  "error": {
    "code": "not_found",
    "message": "no deploy 3f9a2b1c",
    "details": {}
  }
}

code is a stable snake_case string scripts can switch on; message is an English sentence for people. Limits answer 403 or 422 with a code naming the limit and the level that refused.

Lists

?limit=&cursor= with {"items": [...], "next_cursor": "..."}; filters are query parameters.

Values

Times are RFC 3339 in UTC; sizes are bytes; durations are seconds, or lifetimes like 12h, 3d, never.
Ids are short random lowercase hex or prefixed (app_…; secrets xv_…, sk-xvii-…, cfg_…).
Names that appear in host names are DNS labels.

Every service has

Endpoint
`GET /api/v1/meta`	name, version, capabilities
`GET /api/v1/health`, `GET /healthz`	is it up
`GET /api/v1/search?q=`	its resources matching a query (home's ⌘K asks all of them)
`POST /mcp`	its MCP tools, authorized like the API

Changes

Additive changes happen in place. A breaking change needs /api/v2, and /api/v1 keeps working.

Public endpoints

Some endpoints need no token on purpose: home's /api/v1/catalog, /install.sh and /releases/; status pages and heartbeats; analytics' script and event intake; errors' ingest (with the DSN); config's delivery (with an environment key); share's public drops; hooks' and tunnel's endpoints; the docs API.