Information
- License: Licence to be decided
- OpenAPI version:
3.1.0
Overview
Tasks, approvals, the action log, pairing and apps on one box.
GurtOS HTTP API 0.1.0 (preview)
Section titled “GurtOS HTTP API 0.1.0 (preview)”The box’s HTTP API is how the portal, a phone and outside tools list tasks, start them, answer approvals, undo work and follow the action log. These pages are generated from the routes the core serves. For a guided overview, read HTTP API.
Base address
http://127.0.0.1:7700/api. Every route also answers without the /api prefix, so
http://127.0.0.1:7700/tasks and http://127.0.0.1:7700/api/tasks are the same route. The same API
is served on the Unix socket BOX_HOME/api.sock (root only).
Format
Requests and responses are JSON. Send content-type: application/json with a body. A failed request
returns a JSON object with one field, error. Bad input, an unknown task field and an id that does not
exist are 400. A missing, unknown or revoked device token is 401. An owner’s route called by anyone else
is 403. An unknown route is 404.
Who may call what
A request from the box itself (over the Unix socket, or from 127.0.0.1 or ::1 with no proxy header
such as X-Forwarded-For, Forwarded, X-Real-IP, X-Forwarded-Host or Tailscale-User-Login) is
the box’s own screen and needs no token.
Every other request must carry a paired device’s token, as Authorization: Bearer <token> or
?access_token=<token>. Without one the answer is 401. Three things are open: GET /health,
POST /pair and the portal’s own pages.
Some routes are the owner’s: pairing codes and devices, setup, settings, the vault, apps on and off, the owner, folders on a task, Keep and Undo Keep. From outside the box they need a device that was paired as the owner, else 403.
The box listens on 127.0.0.1 by default. BOX_LISTEN changes the address.
Cross-origin requests
The portal is served from the same address as the API and needs no CORS. A browser app on another
origin needs BOX_ORIGINS (a comma-separated list of origins, or *) in the box’s environment.
Not under /api
App routes are served at /t/<app>/... and webhooks at /hook/<app>/<name>. Neither answers under
the /api prefix.
Authentication
Section titled “Authentication”deviceToken
Section titled “deviceToken”A paired device’s token from POST /pair. Required from outside the box on every route but GET /health and POST /pair. Requests from the box itself need none.
Security scheme type: http
accessToken
Section titled “accessToken”The same device token as a query parameter, for clients that cannot send headers, such as a browser’s EventSource on /log/stream.
Security scheme type: apiKey
Query parameter name: access_token
GurtOS is open source under the Apache License 2.0.Source code on GitHub.