{ "openapi": "3.1.0", "info": { "title": "Jinn API", "version": "1", "description": "Run agent work as a call: a prompt and a folder in, a folder out. Authenticate with an account key (Authorization: Bearer jinn_\u2026). Docs: https://docs.usejinn.com" }, "servers": [ { "url": "https://api.usejinn.com" } ], "security": [ { "key": [] } ], "components": { "securitySchemes": { "key": { "type": "http", "scheme": "bearer", "description": "An account key (jinn_\u2026), or a person's ID token with Jinn-Account." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "What went wrong, in words." } }, "required": [ "error" ] }, "ManifestEntry": { "type": "object", "properties": { "path": { "type": "string", "description": "A file, or a folder when it ends in /." }, "description": { "type": "string" }, "max_bytes": { "type": "integer" } }, "required": [ "path", "max_bytes" ] }, "CustomTool": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "description": { "type": "string" }, "parameters": { "type": "object", "description": "A JSON Schema object for the arguments." }, "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "description": "Sent once; never returned." }, "secret_id": { "type": "string", "description": "The sec_\u2026 an earlier version of this function stored for a tool at this URL." }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 600 } }, "required": [ "name", "description", "parameters", "url", "timeout_seconds" ] }, "EnvVar": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "secret": { "type": "string", "description": "Sent once; never returned." }, "secret_id": { "type": "string" } }, "required": [ "name" ] }, "Definition": { "type": "object", "properties": { "base": { "type": "string", "description": "One of GET /v1/bases." }, "setup": { "type": "array", "items": { "type": "string" }, "maxItems": 64, "description": "Commands run as root before the agent, each in bash -euo pipefail -c, with network access and the environment." }, "provider": { "type": "string", "description": "prv_\u2026@3 or prv_\u2026@latest." }, "system_prompt": { "type": "string" }, "tools": { "type": "array", "items": { "type": "string", "enum": [ "bash", "read", "write", "edit", "screenshot", "web_search" ] } }, "custom_tools": { "type": "array", "items": { "$ref": "#/components/schemas/CustomTool" } }, "input_manifest": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestEntry" } }, "output_manifest": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestEntry" } }, "environment": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVar" } }, "size": { "type": "string", "enum": [ "s", "m", "l", "xl" ] }, "timeout_minutes": { "type": "integer", "minimum": 1 } }, "required": [ "base", "provider", "system_prompt", "tools", "custom_tools", "input_manifest", "output_manifest", "size", "timeout_minutes" ] }, "Version": { "allOf": [ { "$ref": "#/components/schemas/Definition" }, { "type": "object", "properties": { "function": { "type": "string" }, "version": { "type": "integer" }, "external_reference": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" } } } ] }, "Function": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "latest": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string" } } }, "Run": { "type": "object", "properties": { "id": { "type": "string" }, "account": { "type": "string" }, "function": { "type": "string" }, "version": { "type": "integer" }, "base": { "type": "string" }, "size": { "type": "string" }, "provider": { "type": "string" }, "prompt": { "type": "string" }, "input": { "type": "string" }, "webhook": { "type": "string" }, "external_reference": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": "string", "format": "date-time" }, "failure": { "type": "string", "enum": [ "input", "no_submission", "timeout", "provider", "infrastructure", "setup", "suspended" ] }, "detail": { "type": "string" }, "message": { "type": "string" }, "output": { "type": "object", "properties": { "sha256": { "type": "string" }, "bytes": { "type": "integer" }, "file_count": { "type": "integer" }, "url": { "type": "string", "description": "The output .tar; works for 15 minutes." }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "bytes": { "type": "integer" }, "dir": { "type": "boolean" } } } } } }, "usage": { "type": "object", "properties": { "compute": { "type": "object", "properties": { "size": { "type": "string" }, "seconds": { "type": "integer" } } }, "model": { "type": "object", "properties": { "calls": { "type": "integer" }, "input_tokens": { "type": "integer" }, "cache_read_tokens": { "type": "integer" }, "cache_write_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "web_searches": { "type": "integer" } } } } } } }, "Model": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "anthropic", "xai" ] }, "model": { "type": "string" }, "reasoning_effort": { "type": "string" }, "compact_at_tokens": { "type": "integer", "minimum": 8000 }, "max_output_tokens": { "type": "integer" } }, "required": [ "provider", "model", "compact_at_tokens" ] }, "Provider": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "name": { "type": "string" }, "model": { "$ref": "#/components/schemas/Model" }, "external_reference": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" } } }, "Key": { "type": "object", "properties": { "id": { "type": "string" }, "account": { "type": "string" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "admin", "run" ] }, "functions": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "revoked_at": { "type": "string", "format": "date-time" }, "revoked_by": { "type": "string" } } }, "Member": { "type": "object", "properties": { "account": { "type": "string" }, "user": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] }, "joined_at": { "type": "string", "format": "date-time" }, "invited_by": { "type": "string" } } }, "Invite": { "type": "object", "properties": { "email": { "type": "string" }, "account": { "type": "string" }, "account_name": { "type": "string" }, "role": { "type": "string" }, "invited_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "integer" } } }, "Balance": { "type": "object", "properties": { "account": { "type": "string" }, "balance_usd_nanos": { "type": "integer" }, "minimum_balance_usd_nanos": { "type": "integer" }, "currency": { "type": "string" }, "available_usd_nanos": { "type": "integer" } } }, "Entry": { "type": "object", "properties": { "id": { "type": "string" }, "account": { "type": "string" }, "kind": { "type": "string", "enum": [ "compute", "purchase", "refund", "dispute", "adjustment" ] }, "amount_usd_nanos": { "type": "integer" }, "effective_at": { "type": "string", "format": "date-time" }, "run": { "type": "string" }, "function": { "type": "string" }, "version": { "type": "integer" }, "size": { "type": "string" }, "provider": { "type": "string" }, "started_by": { "type": "string" }, "external_reference": { "type": "string" }, "from_minute": { "type": "integer" }, "through_minute": { "type": "integer" }, "memory_mib": { "type": "integer" }, "rate_usd_nanos_per_gib_hour": { "type": "integer" } } } } }, "paths": { "/v1/files": { "post": { "summary": "Upload a run's input folder: send its size and SHA-256, then PUT the .tar to the returned url with the returned headers.", "x-jinn-access": "member", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "method": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bytes": { "type": "integer" }, "sha256": { "type": "string" } }, "required": [ "bytes", "sha256" ] } } } } } }, "/v1/bases": { "get": { "summary": "List the bases a function can boot.", "x-jinn-access": "member", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "bases": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "sha256": { "type": "string" }, "bytes": { "type": "integer" } } } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/functions": { "get": { "summary": "List the account's functions with their latest definition and last run.", "x-jinn-access": "member", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "functions": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Function" }, { "type": "object", "properties": { "definition": { "$ref": "#/components/schemas/Version" }, "last": { "$ref": "#/components/schemas/Run" } } } ] } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Make a function, with a new id, and its first version.", "x-jinn-access": "member (admin keys)", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$" }, "external_reference": { "type": "string" } }, "required": [ "name" ] }, { "$ref": "#/components/schemas/Definition" } ] } } } } } }, "/v1/functions/{id}": { "get": { "summary": "A function and its versions, oldest first.", "x-jinn-access": "member", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "function": { "$ref": "#/components/schemas/Function" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/Version" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/functions/{id}/versions": { "post": { "summary": "Publish a function's next version.", "x-jinn-access": "member (admin keys)", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Definition" }, { "type": "object", "properties": { "external_reference": { "type": "string" } } } ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/functions/{id}/runs": { "post": { "summary": "Start a run. Every call is a new run.", "x-jinn-access": "member", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "description": "0 or absent: the latest" }, "prompt": { "type": "string", "maxLength": 131072 }, "input": { "type": "string", "description": "file_\u2026" }, "webhook": { "type": "string", "format": "uri" }, "external_reference": { "type": "string" } }, "required": [ "prompt" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/runs": { "get": { "summary": "List runs, newest first. A run key must name a function.", "x-jinn-access": "member", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "next": { "type": "string", "description": "Pass as before for the next page." } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "function", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "active", "succeeded", "failed" ] } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/v1/runs/{id}": { "get": { "summary": "Read a run. A succeeded run's output.url works for 15 minutes.", "x-jinn-access": "member", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/runs/{id}/log": { "get": { "summary": "Links to the run's log parts, in order: JSON lines of {at, kind, \u2026}.", "x-jinn-access": "member", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "string" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/providers": { "get": { "summary": "List providers and their versions, newest first.", "x-jinn-access": "member (admin keys)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "latest": { "type": "integer" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Make a provider and its first version. The key is checked against the vendor's catalog and never returned.", "x-jinn-access": "member (admin keys)", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "$ref": "#/components/schemas/Model" }, "key": { "type": "string" }, "external_reference": { "type": "string" } }, "required": [ "name", "model", "key" ] } } } } } }, "/v1/providers/{id}/versions": { "post": { "summary": "Publish a provider's next version: a new key, a new model or both.", "x-jinn-access": "member (admin keys)", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/Model" }, "key": { "type": "string" }, "external_reference": { "type": "string" } }, "required": [ "model", "key" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/catalog": { "post": { "summary": "List the models a vendor key can use. The key is used once and kept nowhere.", "x-jinn-access": "member (admin keys)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "context_window": { "type": "integer" }, "max_output_tokens": { "type": "integer" }, "efforts": { "type": "array", "items": { "type": "string" } }, "default_effort": { "type": "string" } } } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "anthropic", "xai" ] }, "key": { "type": "string" } }, "required": [ "provider", "key" ] } } } } } }, "/v1/webhooks/public-key": { "get": { "summary": "The account's webhook public key (whpk_\u2026, Ed25519).", "x-jinn-access": "member", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "string" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me": { "get": { "summary": "Who is signed in: their accounts and the invites waiting for them.", "x-jinn-access": "signed in", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string" }, "email": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "role": { "type": "string" } } } }, "invites": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/invites/{account}/accept": { "post": { "summary": "Accept an invite.", "x-jinn-access": "signed in", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/account": { "get": { "summary": "The account, its limits, its balance and your role.", "x-jinn-access": "person", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "limits": { "type": "object", "properties": { "memory_mib": { "type": "integer" }, "sizes": { "type": "array", "items": { "type": "string" } } } }, "webhook_public_key": { "type": "string" }, "balance": { "$ref": "#/components/schemas/Balance" }, "role": { "type": "string" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/members": { "get": { "summary": "List the account's members.", "x-jinn-access": "person", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/members/{user}": { "delete": { "summary": "Remove a member; an account keeps one owner.", "x-jinn-access": "owner", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "string" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/invites": { "get": { "summary": "List invites waiting.", "x-jinn-access": "owner", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] }, "post": { "summary": "Invite an email for 7 days. The invite lets that email sign up.", "x-jinn-access": "owner", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "member" ] } }, "required": [ "email", "role" ] } } } }, "parameters": [ { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/invites/{email}": { "delete": { "summary": "Cancel an invite.", "x-jinn-access": "owner", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "string" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/keys": { "get": { "summary": "List the account's keys. Secrets are never returned.", "x-jinn-access": "owner", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] }, "post": { "summary": "Make a key. The token is returned once.", "x-jinn-access": "owner", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/Key" }, "token": { "type": "string" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "admin", "run" ] }, "functions": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "scope" ] } } } }, "parameters": [ { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/keys/{id}": { "delete": { "summary": "Revoke a key at once.", "x-jinn-access": "owner", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "string" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/usage": { "get": { "summary": "The balance and the last 30 days of the ledger.", "x-jinn-access": "person", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "$ref": "#/components/schemas/Balance" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/credit/checkout": { "post": { "summary": "Buy credit: returns a Stripe Checkout page.", "x-jinn-access": "owner", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_usd_cents": { "type": "integer" } }, "required": [ "amount_usd_cents" ] } } } }, "parameters": [ { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/v1/cli-logins": { "post": { "summary": "Start a CLI login. The CLI keeps the key's secret and sends its SHA-256.", "x-jinn-access": "anyone", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "url": { "type": "string" }, "expires_at": { "type": "integer" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "key_hash": { "type": "string" } }, "required": [ "name", "key_hash" ] } } } }, "security": [] } }, "/v1/cli-logins/{id}": { "get": { "summary": "A CLI login's state; once approved, its account and key id.", "x-jinn-access": "anyone", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "approved" ] }, "account": { "type": "string" }, "key": { "type": "string" }, "expires_at": { "type": "integer" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [] } }, "/v1/cli-logins/{id}/approve": { "post": { "summary": "Approve a CLI login: makes an admin key with the CLI's hash.", "x-jinn-access": "person", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/Key" } } } } } }, "default": { "description": "An error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Jinn-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The account, for a person's token (keys carry theirs)." } ] } }, "/stripe/webhook": { "post": { "summary": "Stripe's events (signed). Not for callers.", "x-jinn-access": "Stripe", "responses": { "200": { "description": "Recorded or ignored" } }, "security": [] } } } }