APIs

JSON over HTTPS at https://<service>.<d>/api/v1/…. Resource-oriented: GET /apps, POST /apps, GET /apps/{id}, PATCH /apps/{id}, DELETE /apps/{id}; actions as POST /apps/{id}/restart.
Auth: Authorization: Bearer <access token or API token>, or the panel's session cookie. Requests carrying a cookie must be same-origin: reject when Sec-Fetch-Site is present and not same-origin, or when Origin is present and not the panel's origin (kit/auth).
Team context: X-Xvii-Team: <team id> header or ?team=; required where a resource is created.
Errors: status code plus {"error": {"code": "not_found", "message": "…", "details": {…}}}. Codes are stable snake_case strings the CLI and panels may switch on; messages are English sentences.
Lists: ?limit=&cursor= with {"items": […], "next_cursor": "…"}; filters as query params.
Times are RFC 3339 UTC; sizes in bytes; durations in seconds or ttl strings (12h, 3d, never).
Ids: short random lowercase hex or prefixed ids (app_…, xv_… for secrets); names are DNS labels where they appear in hosts.
Every change records an audit event and an outbox event (kit/audit, kit/events).
Every service serves GET /api/v1/meta (name, version, capabilities), GET /healthz, GET /api/v1/search?q= and an MCP endpoint at /mcp exposing its main operations as tools, authorized like the API.
Breaking changes need /api/v2; additive changes are fine in place.