Reference
API Access
Authentication, conventions and asynchronous jobs.
Everything in the dashboard goes through the same JSON API under /api/v1. The interactive OpenAPI reference is served by the API at /docs.
Authentication
Requests carry a short-lived access token as a bearer token. Sign-in always takes two steps, because a second factor is required:
bash
# 1. Password: returns a challengecurl -s -X POST https://pilot.example.com/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"…"}'# → {"status":"two_factor_required","challenge_id":"8f1c…","method":"totp", …}# 2. Code: returns an access token (and sets the refresh cookie)curl -s -X POST https://pilot.example.com/api/v1/auth/2fa/verify \ -H "Content-Type: application/json" -c cookies.txt \ -d '{"challenge_id":"8f1c…","code":"123456"}'# → {"status":"authenticated","access_token":"eyJ…","expires_in":900, …}# 3. Call the APIcurl -s https://pilot.example.com/api/v1/servers -H "Authorization: Bearer $TOKEN"Access tokens last 15 minutes. Exchange the refresh cookie for a new one with POST /api/v1/auth/refresh; the cookie rotates on every refresh. Management endpoints require an admin account.
Conventions
Asynchronous operations
Anything that happens on a server returns 202 Accepted with a job, because the work is done by the agent. Poll the job until it finishes:
http
POST /api/v1/databases/{id}/query → 202 {"job_id": "a91e…"}GET /api/v1/databases/{id}/jobs/a91e… → {"status": "running", "error": null, "data": null}GET /api/v1/databases/{id}/jobs/a91e… → {"status": "succeeded", "error": null, "data": {…}}