Jinn docs Console

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:

ScopePermissions
adminRead, 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.
runUpload 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.
imageDelete 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

RouteFunction
POST /filesStarts 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 /functionsLists the functions. Each function has its latest definition and its last run.
POST /functionsMakes a function and its first version. Send name and a definition.
GET /functions/{id}Returns a function and its versions.
POST /functions/{id}/versionsPublishes the next version.
DELETE /functions/{id}Deletes a function, its versions and their secrets. See Delete a function.
POST /functions/{id}/runsStarts a run. With an Idempotency-Key header, a repeated start returns the first run. See Runs.
GET /runsLists 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}/logReturns links to the parts of the log of the run, and to the images that its commands returned.
POST /runs/{id}/commandsSends a command. See Commands.
GET /runs/{id}/commandsLists 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}/outputReturns 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}/cancelCancels a command.
POST /runs/{id}/terminalCreates a single-use 30-second WebSocket terminal ticket for an active run.
GET /ssh-keysLists the authorised SSH public keys of the account (admin keys).
POST /ssh-keysAdds an SSH public key (name, public_key).
DELETE /ssh-keys/{id}Deletes an SSH public key.
GET /machinesLists the persistent machines of the account (admin keys). See Machines.
POST /machinesCreates 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}/startBoots a stopped machine.
POST /machines/{id}/stopSaves the disk of a running machine and stops it.
POST /machines/{id}/snapshotCopies a stopped machine's current disk to a standalone img_….
POST /machines/{id}/terminalCreates a single-use 30-second WebSocket terminal ticket for a running machine.
GET /imagesLists 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 /toolsReturns the tools that Jinn's agent gives to its model, with their JSON Schemas.
GET /providersLists the providers and their versions.
POST /providersMakes a provider. Send name, model and key.
POST /providers/{id}/versionsPublishes 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 /catalogLists the models that a vendor key can use. Send provider and key. Jinn does not keep the key.
GET /webhooks/public-keyReturns 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).

StatuscodeMeaning
400invalid_requestThe request is not correct. The message gives the name of the field.
400invalid_signatureThe signature of a Stripe webhook is not correct.
400account_requiredThe token of a person must have the Jinn-Account header.
401unauthenticatedThe key or token is missing, incorrect, expired or revoked.
402no_creditThe balance of the account is at its minimum. Runs cannot start.
403key_scopeThe scopes of the key do not let it use this route.
403people_onlyThe route is for persons who signed in to the console. Keys cannot use it.
403not_a_memberThe person is not a member of the account.
403owners_onlyThe route is for the owners of the account.
403suspendedJinn suspended the account.
404not_foundThe route does not exist, or the item is not in this account.
405method_not_allowedThe route does not accept this method.
409conflictA different write changed the same item first. Retry.
500internalAn error occurred in Jinn. Retry. If the error continues, write to support@usejinn.com.
502vendor_unavailableJinn could not read the model catalog of the vendor.
503purchases_closedYou cannot buy credit at this time.
400 or 404image_not_foundThe image does not exist, or a person deleted it (GET /v1/images).
400image_too_largeThe disk of the image is larger than the disk of the size of the function.
400prompt_requiredThe function has an agent. Send the task of the agent as prompt.
400prompt_not_allowedThe function has no agent. Do not send a prompt. Use commands to control the run.
404command_not_foundThe command is not in this run.
409run_endedThe run ended. It does not accept more commands.
409runs_activeThe function has runs that did not end. Finish them, or wait for them to end. Then delete the function or the provider.
409provider_in_useThe latest version of a function names the provider. Publish a version with a different provider, or delete the function. Then delete the provider.
409ssh_key_existsThe account already holds this SSH public key.
404ssh_key_not_foundThe SSH key is not in this account.
409machine_existsA machine with this name already exists in this account.
404machine_not_foundThe machine is not in this account.
409machine_activeStop the machine before you resize, snapshot or delete it.
409machine_stoppingThe machine is saving its disk. Wait until it stops, then try again.
409machine_stoppedStart the machine before you open a terminal.
409image_in_useA machine uses this image as its disk. Delete the machine first.
409image_deletedJinn deleted the disk image of this machine after storage grace ended.