REST API

The gateway serves its API under /api/. The full description, with request and response schemas, is an OpenAPI 3.1 document:

• On a running install: https://<javo address>/api/openapi.json, without sign-in.
• With config.api.docs.enabled, an interactive Swagger UI at /api/docs/ (its files ship in the image; nothing loads from a CDN).
• The same document as built from this version of the code: openapi.json. javo openapi prints it too, with no cluster needed.

Authentication

Scheme	How
Personal API token	Authorization: Bearer <token>. A read token may only read; tokens cannot manage tokens. See API tokens.
Browser session	The javo_session cookie set at sign-in, used by the web UI.

Endpoints

admin

Method	Path	What it does
POST	/api/admin/ai/ask	Platform admins: ask about the report; the answer cites its rows and changes nothing
GET	/api/admin/apps	Every person's apps, newest first (platform admins)
GET	/api/admin/backups	The database backups and their health (platform admins)
POST	/api/admin/backups	Back up the database now (platform admins)
POST	/api/admin/backups/now	Run the backup job now (platform admins)
POST	/api/admin/backups/restore	Run the restore job now: a full backup, for everyone or one person (platform admins)
POST	/api/admin/backups/restores	Restore a full backup, for everyone or one person, as part of a run of the restore job (its run calls this)
GET	/api/admin/backups/restores/{run}	Where a restore stands, home by home
POST	/api/admin/backups/runs	Start a full backup as part of a run of the backup job (its run calls this)
GET	/api/admin/backups/runs/{run}	Where a full backup stands, step by step
POST	/api/admin/backups/{name}/preview	What restoring apps from a database backup would do; nothing is changed (platform admins)
POST	/api/admin/backups/{name}/restore	Bring back apps from a database backup; they wait for a release (platform admins)
GET	/api/admin/report	Platform admins: failures by cause, apps by state and template, idle apps
GET	/api/admin/restores	Restores whose apps wait to be released (platform admins)
POST	/api/admin/restores/{name}/release	Let a restore's held apps go (platform admins)
GET	/api/admin/usage	How long apps ran in the last days, per person or group (platform admins)

ai

Method	Path	What it does
POST	/api/ai/command	Ask in plain words for changes to your apps; each comes back as a plan to approve
POST	/api/ai/draft	Fill the new app form from a description; nothing is created
POST	/api/ai/feedback	Say whether an AI answer was right (logged, nothing else)
GET	/api/ai/status	Which AI features are on
POST	/api/workspaces/{name}/diagnosis/explain	Ask the model to explain a failure; its evidence is checked against what was sent

auth

Method	Path	What it does
POST	/api/auth/local/login	Sign in with a local account
POST	/api/auth/logout	Sign out and end the session
GET	/api/auth/options	The ways to sign in
GET	/api/info	Which optional parts of the server are on
GET	/api/me	The signed-in user
GET	/api/reasons	The words for one catalog reason

branding

Method	Path	What it does
GET	/api/branding	The install's product name, logo, favicon and accent

environments

Method	Path	What it does
GET	/api/environments	List the environments you can run an app or a job in

files

Method	Path	What it does
GET	/api/files	List a folder of the user's home
GET	/api/files/raw	Download or show one file of the user's home
POST	/api/files/warm	Get the user's home folder ready to list

jobs

Method	Path	What it does
GET	/api/engines	The ways a file can be run as a job
POST	/api/job-samples/{template}	Make a template's sample job (run on demand)
GET	/api/jobs	The user's jobs
POST	/api/jobs	Create a job
GET	/api/jobs/{name}	One of the user's jobs with its runs
PUT	/api/jobs/{name}	Change a job
DELETE	/api/jobs/{name}	Delete a job (its run folders are kept)
PUT	/api/jobs/{name}/env	Set a job's environment variables: plain values and values from your secrets (from the next run on)
POST	/api/jobs/{name}/pause	Pause a job's schedule
POST	/api/jobs/{name}/resume	Resume a job's schedule
POST	/api/jobs/{name}/run	Run a job now
POST	/api/jobs/{name}/runs/{run}/cancel	Cancel a run that is still going
GET	/api/jobs/{name}/runs/{run}/log	A run's log as plain text, followed live while the run is going
PUT	/api/jobs/{name}/size	Change the size or custom amount a job's runs get (from the next run on)
POST	/api/schedule/preview	Upcoming run times of a schedule, as the cluster will run them

plans

Method	Path	What it does
POST	/api/plans	Propose a change for review; nothing changes until it is approved
GET	/api/plans/{id}	A proposed change and its state
POST	/api/plans/{id}/approve	Approve and make a proposed change (browser session only)
POST	/api/plans/{id}/reject	Turn down a proposed change (browser session only)

secrets

Method	Path	What it does
GET	/api/secrets	Your secrets: names, notes, dates and the apps and jobs that use them, never the values
POST	/api/secrets	Store a secret
PUT	/api/secrets/{name}	Replace a secret's value or change its note
DELETE	/api/secrets/{name}	Delete a secret no app or job uses

sharing

Method	Path	What it does
GET	/api/directory	People and the caller's own groups matching a search
GET	/api/shared	Apps other people shared with the user
GET	/api/workspaces/{name}/sharing	Who can open one of the user's apps
PUT	/api/workspaces/{name}/sharing	Change who can open one of the user's apps

storage

Method	Path	What it does
GET	/api/admin/storage	Storage capability report
GET	/api/storage	What the caller's files are on
GET	/api/storage/placement	Where a new app would run

templates

Method	Path	What it does
GET	/api/templates	Templates the user may create apps from
PUT	/api/templates/{name}	Create or replace a template (template admins)
DELETE	/api/templates/{name}	Delete a template (template admins)

tokens

Method	Path	What it does
GET	/api/tokens	Your personal API tokens
POST	/api/tokens	Create a personal API token
DELETE	/api/tokens/{id}	Revoke a personal API token

workspaces

Method	Path	What it does
GET	/api/idle-stop	The allowed "Stop when idle" timeouts and the default for new apps
GET	/api/previews	Whether new apps can have pull request previews, and their limits
POST	/api/previews/webhook	Make a webhook address and secret for an app not yet created (shown once)
POST	/api/samples/{template}	Start a template's sample app
GET	/api/sizes	Sizes the caller can run an app at, and their custom amount allowance
GET	/api/workspaces	The user's apps
POST	/api/workspaces	Create an app
GET	/api/workspaces/export	The user's apps as a YAML file to keep or import elsewhere
POST	/api/workspaces/import	Import a YAML file of apps; they arrive stopped and private
POST	/api/workspaces/import/preview	What importing a YAML file of apps would do; nothing is changed
GET	/api/workspaces/{name}	One of the user's apps
DELETE	/api/workspaces/{name}	Delete an app (the home folder is kept)
PUT	/api/workspaces/{name}/api-access	Change whether an app can call the API as you (a running app restarts)
GET	/api/workspaces/{name}/diagnosis	Why an app failed: the cause the rules found, its evidence and the changes that may fix it
PUT	/api/workspaces/{name}/env	Set an app's environment variables: plain values and values from your secrets (a running app restarts)
GET	/api/workspaces/{name}/events	Kubernetes events of an app's pod and home folder (with the Job that readies it), oldest first; the home step's warnings come before its other events
PUT	/api/workspaces/{name}/idle-stop	Change when an app stops for being idle (a running app keeps running)
PUT	/api/workspaces/{name}/launch	Change an app's command, and for an image app its image and port (a running app restarts)
GET	/api/workspaces/{name}/logs	The latest lines the app wrote
GET	/api/workspaces/{name}/logs/stream	Follow the app's log live (server-sent events, one line event per log line)
GET	/api/workspaces/{name}/previews	The app's preview settings and what the last look at its pull requests found
PUT	/api/workspaces/{name}/previews	Turn pull request previews on or off and set how many (GitHub repositories only)
POST	/api/workspaces/{name}/previews/webhook	Make the webhook address and secret that start a preview sync at once (shown once; replaces any earlier pair)
POST	/api/workspaces/{name}/redeploy	Pull the newest commit (or home file) and restart the app
POST	/api/workspaces/{name}/restart	Restart an app (its pod is replaced; a stopped app stays stopped)
PUT	/api/workspaces/{name}/size	Change an app's size or custom amount (a running app restarts)
PUT	/api/workspaces/{name}/source/token	Take the access token of the app's private repository from one of your secrets (the app restarts)
DELETE	/api/workspaces/{name}/source/token	Clone the app's repository without an access token (the app restarts)
POST	/api/workspaces/{name}/start	Start an app
GET	/api/workspaces/{name}/steps/{step}/log	Follow the log of the containers doing a startup step's work, one after another, as they write it (newline-delimited JSON records; ends once every one of them has finished)
POST	/api/workspaces/{name}/stop	Stop an app
GET	/api/workspaces/{name}/thumbnail	The app's picture, for anyone who may open the app
PUT	/api/workspaces/{name}/thumbnail	Set the picture shown on the app's card (owner or platform admin)
DELETE	/api/workspaces/{name}/thumbnail	Remove the app's picture; its card shows the app kind's logo again