API
Updated 2026-11-21
The base URL of the API is https://api.usejinn.com/v1. Requests and responses are JSON. openapi.json describes all routes and fields.
Authentication
Send an account key as a bearer token:
$ curl https://api.usejinn.com/v1/functions -H "Authorization: Bearer $JINN_KEY"
An owner makes keys on the Account page of the console. jinn login makes a key for the CLI. A key is for one account. The console shows the token of a key one time only. When you revoke a key, the key stops immediately.
Each key has one or more scopes. A key has admin alone, or run, image or the two:
| Scope | Permissions |
|---|---|
admin | Read, publish and delete functions and providers. Manage machines and SSH keys. Upload files. Start all runs of the account, read them and send commands to them. Delete images. |
run | Upload files. Start the functions that the key names, read their runs and send commands to their runs. With ["*"], the key can start all functions of the account, also the functions that you make after the key. |
image | Delete the images of the account. |
All keys can list and read images. A key with run and image can start runs that save images, boot them and delete the old images.
A key that can start a function can send commands to its runs. Thus the key can read the secret variables of the function in the VM.
A key cannot manage members, invites, keys or credit. Only a person who signed in to the console can do these tasks.
Routes
| Route | Function |
|---|---|
POST /files | Starts an upload. Send bytes and sha256. Then PUT the file to the url of the response, with the headers of the response. Returns the id of the upload (file_…). |
GET /functions | Lists the functions. Each function has its latest definition and its last run. |
POST /functions | Makes a function and its first version. Send name and a definition. |
GET /functions/{id} | Returns a function and its versions. |
POST /functions/{id}/versions | Publishes the next version. |
DELETE /functions/{id} | Deletes a function, its versions and their secrets. See Delete a function. |
POST /functions/{id}/runs | Starts a run. With an Idempotency-Key header, a repeated start returns the first run. See Runs. |
GET /runs | Lists runs, newest first, 50 on each page. The filters are function and state (active, succeeded, failed). For the next page, send the next of the response as before. A key with the run scope must send function. |
GET /runs/{id} | Returns a run. |
GET /runs/{id}/log | Returns links to the parts of the log of the run, and to the images that its commands returned. |
POST /runs/{id}/commands | Sends a command. See Commands. |
GET /runs/{id}/commands | Lists the commands that changed after since. With wait, the request waits a maximum of 25 seconds for a change. |
GET /runs/{id}/commands/{cid} | Returns a command. With wait, the request waits a maximum of 25 seconds for the command to end. |
GET /runs/{id}/commands/{cid}/output | Returns the output of a bash command from after. With wait, the request waits a maximum of 25 seconds for more output. |
POST /runs/{id}/commands/{cid}/cancel | Cancels a command. |
POST /runs/{id}/terminal | Creates a single-use 30-second WebSocket terminal ticket for an active run. |
GET /ssh-keys | Lists the authorised SSH public keys of the account (admin keys). |
POST /ssh-keys | Adds an SSH public key (name, public_key). |
DELETE /ssh-keys/{id} | Deletes an SSH public key. |
GET /machines | Lists the persistent machines of the account (admin keys). See Machines. |
POST /machines | Creates a stopped machine (name?, size?, image?, idle_minutes?). |
GET /machines/{id} | Returns a machine by id (mch_…), slug or name. |
PATCH /machines/{id} | Updates name, idle_minutes, or size (when stopped). |
DELETE /machines/{id} | Deletes a stopped machine and its unshared disk image. |
POST /machines/{id}/start | Boots a stopped machine. |
POST /machines/{id}/stop | Saves the disk of a running machine and stops it. |
POST /machines/{id}/snapshot | Copies a stopped machine's current disk to a standalone img_…. |
POST /machines/{id}/terminal | Creates a single-use 30-second WebSocket terminal ticket for a running machine. |
GET /images | Lists the images of the account and the Jinn bases. See Images. |
GET /images/{id} | Returns an image or a base. |
DELETE /images/{id} | Deletes an image of the account. |
GET /tools | Returns the tools that Jinn's agent gives to its model, with their JSON Schemas. |
GET /providers | Lists the providers and their versions. |
POST /providers | Makes a provider. Send name, model and key. |
POST /providers/{id}/versions | Publishes the next version of a provider. Send model and key. |
DELETE /providers/{id} | Deletes a provider, its versions and their keys. Jinn refuses the delete with provider_in_use if the latest version of a function names the provider. Jinn refuses it with runs_active while a run that uses the provider is queued or running. |
POST /catalog | Lists the models that a vendor key can use. Send provider and key. Jinn does not keep the key. |
GET /webhooks/public-key | Returns the webhook public key of the account. |
Errors
If Jinn refuses a request, the response has an HTTP status and a body. The body has a stable code and a message for persons:
{"code": "no_credit", "error": "this account has no credit left; an owner can add credit in the console"}
Use code in your code, not the message. The message can change. Retry conflict and internal. Retry vendor_unavailable after some seconds. For all other codes, change the request before you send it again. To retry the start of a run safely, send an Idempotency-Key header (see Start a run one time).
| Status | code | Meaning |
|---|---|---|
400 | invalid_request | The request is not correct. The message gives the name of the field. |
400 | invalid_signature | The signature of a Stripe webhook is not correct. |
400 | account_required | The token of a person must have the Jinn-Account header. |
401 | unauthenticated | The key or token is missing, incorrect, expired or revoked. |
402 | no_credit | The balance of the account is at its minimum. Runs cannot start. |
403 | key_scope | The scopes of the key do not let it use this route. |
403 | people_only | The route is for persons who signed in to the console. Keys cannot use it. |
403 | not_a_member | The person is not a member of the account. |
403 | owners_only | The route is for the owners of the account. |
403 | suspended | Jinn suspended the account. |
404 | not_found | The route does not exist, or the item is not in this account. |
405 | method_not_allowed | The route does not accept this method. |
409 | conflict | A different write changed the same item first. Retry. |
500 | internal | An error occurred in Jinn. Retry. If the error continues, write to support@usejinn.com. |
502 | vendor_unavailable | Jinn could not read the model catalog of the vendor. |
503 | purchases_closed | You cannot buy credit at this time. |
400 or 404 | image_not_found | The image does not exist, or a person deleted it (GET /v1/images). |
400 | image_too_large | The disk of the image is larger than the disk of the size of the function. |
400 | prompt_required | The function has an agent. Send the task of the agent as prompt. |
400 | prompt_not_allowed | The function has no agent. Do not send a prompt. Use commands to control the run. |
404 | command_not_found | The command is not in this run. |
409 | run_ended | The run ended. It does not accept more commands. |
409 | runs_active | The function has runs that did not end. Finish them, or wait for them to end. Then delete the function or the provider. |
409 | provider_in_use | The latest version of a function names the provider. Publish a version with a different provider, or delete the function. Then delete the provider. |
409 | ssh_key_exists | The account already holds this SSH public key. |
404 | ssh_key_not_found | The SSH key is not in this account. |
409 | machine_exists | A machine with this name already exists in this account. |
404 | machine_not_found | The machine is not in this account. |
409 | machine_active | Stop the machine before you resize, snapshot or delete it. |
409 | machine_stopping | The machine is saving its disk. Wait until it stops, then try again. |
409 | machine_stopped | Start the machine before you open a terminal. |
409 | image_in_use | A machine uses this image as its disk. Delete the machine first. |
409 | image_deleted | Jinn deleted the disk image of this machine after storage grace ended. |