{ "$comment": "SPDX-License-Identifier: Apache-2.0. Generated from internal/server route table; do not edit by hand.", "components": { "securitySchemes": { "apiToken": { "bearerFormat": "oak_pat_...", "description": "An API token the account made for scripts. It reaches the account's data in apps, as its scopes allow, and never the account itself.", "scheme": "bearer", "type": "http" }, "appToken": { "description": "An app's access token, from the sign-in flow (it lasts 5 minutes; the refresh token renews it). It is valid only on the app routes of the installation it was issued for.", "scheme": "bearer", "type": "http" }, "sessionCookie": { "description": "HttpOnly session cookie plus X-CSRF-Token header on mutations.", "in": "cookie", "name": "cloudoak_session", "type": "apiKey" } } }, "info": { "description": "The HTTP API every Cloudoak node serves: accounts, sign-in, and each app's tables, documents, vectors, files and change feed. Generated from the node's route table.", "license": { "identifier": "Apache-2.0", "name": "Apache License 2.0" }, "title": "Cloudoak API", "version": "2.1.0" }, "openapi": "3.1.0", "paths": { "/api/v1/apps/{appId}/buckets/{bucket}/files": { "get": { "description": "The ready files the caller may read.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "files": { "items": { "properties": { "bucket": { "type": "string" }, "contentType": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "bucket", "name", "size", "contentType", "owner", "createdAt", "status" ], "type": "object" }, "type": "array" } }, "required": [ "files" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "List ready files", "tags": [ "files" ] }, "post": { "description": "Reserves an upload: name, size and content type, checked against the bucket's limits and the account's quota. The answer has a presigned PUT address, valid for 15 minutes. Upload the bytes there, then call finalize.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "contentType": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "name", "size", "contentType" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "expiresAt": { "type": "string" }, "file": { "properties": { "bucket": { "type": "string" }, "contentType": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "bucket", "name", "size", "contentType", "owner", "createdAt", "status" ], "type": "object" }, "putUrl": { "type": "string" } }, "required": [ "file", "putUrl", "expiresAt" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Reserve an upload and presign PUT", "tags": [ "files" ] } }, "/api/v1/apps/{appId}/buckets/{bucket}/files/{id}": { "delete": { "description": "Deletes a file and its stored bytes.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Delete a file and its object", "tags": [ "files" ] }, "get": { "description": "A file's details, with a presigned GET address valid for 5 minutes.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "expiresAt": { "type": "string" }, "file": { "properties": { "bucket": { "type": "string" }, "contentType": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "bucket", "name", "size", "contentType", "owner", "createdAt", "status" ], "type": "object" }, "getUrl": { "type": "string" } }, "required": [ "file", "getUrl", "expiresAt" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "File metadata with presigned GET", "tags": [ "files" ] } }, "/api/v1/apps/{appId}/buckets/{bucket}/files/{id}/finalize": { "post": { "description": "Checks what was uploaded against the reservation and marks the file ready. A reservation nobody finalizes is released after a while, with whatever was uploaded for it.", "requestBody": { "content": { "application/json": { "schema": { "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "bucket": { "type": "string" }, "contentType": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "bucket", "name", "size", "contentType", "owner", "createdAt", "status" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Verify the upload and mark ready", "tags": [ "files" ] } }, "/api/v1/apps/{appId}/changes": { "get": { "description": "The app's change feed, for sync: what was created, updated or deleted since a cursor. Query parameters: since (the next value of the last answer; leave it out to start from the beginning, or send latest to start from now) and limit (default 100, at most 1000). Store next and send it back. When resync is true, the cursor cannot be continued: reload what you show, then follow the feed from next. Apps poll this; there is no push channel.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "changes": { "items": { "properties": { "at": { "type": "string" }, "kind": { "type": "string" }, "op": { "type": "string" }, "rowId": { "type": "string" }, "seq": { "type": "integer" }, "table": { "type": "string" } }, "required": [ "seq", "kind", "table", "rowId", "op", "at" ], "type": "object" }, "type": "array" }, "next": { "type": "string" }, "resync": { "type": "boolean" } }, "required": [ "changes", "next" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Change feed for sync (since an opaque cursor)", "tags": [ "sync" ] } }, "/api/v1/apps/{appId}/collections/{collection}/docs": { "get": { "description": "A page of the documents the caller may read. Query parameters: limit (default 50, at most 1000) and cursor.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "next": { "type": "string" }, "rows": { "items": { "type": "object" }, "type": "array" } }, "required": [ "rows" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "List documents", "tags": [ "documents" ] }, "post": { "description": "Creates a JSON document. The caller owns it.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "values": { "type": "object" } }, "required": [ "values" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Create a document", "tags": [ "documents" ] } }, "/api/v1/apps/{appId}/collections/{collection}/docs/{id}": { "delete": { "description": "Deletes a document the caller may delete.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Delete a document", "tags": [ "documents" ] }, "get": { "description": "One document, with its version.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "One document", "tags": [ "documents" ] }, "patch": { "description": "Merges fields into a document's data. It needs the version the caller last read, in the body or as If-Match; 409 when it changed since.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "values": { "type": "object" }, "version": { "type": "integer" } }, "required": [ "values" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Merge a document (version-checked)", "tags": [ "documents" ] }, "put": { "description": "Replaces a document's data. It needs the version the caller last read, in the body or as If-Match; 409 when it changed since.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "values": { "type": "object" }, "version": { "type": "integer" } }, "required": [ "values" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Replace a document (version-checked)", "tags": [ "documents" ] } }, "/api/v1/apps/{appId}/collections/{collection}/docs:query": { "post": { "description": "Documents matching a filter on their top-level fields, with the same filter language, sort, limit and cursor as table queries.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "cursor": { "type": "string" }, "filter": { "properties": { "and": { "items": { "description": "recursive", "type": "object" }, "type": "array" }, "field": { "type": "string" }, "not": { "description": "recursive", "type": "object" }, "op": { "type": "string" }, "or": { "items": { "description": "recursive", "type": "object" }, "type": "array" }, "value": {} }, "type": "object" }, "limit": { "type": "integer" }, "select": { "items": { "type": "string" }, "type": "array" }, "sort": { "items": { "properties": { "dir": { "type": "string" }, "field": { "type": "string" } }, "required": [ "field", "dir" ], "type": "object" }, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "next": { "type": "string" }, "rows": { "items": { "type": "object" }, "type": "array" } }, "required": [ "rows" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Query documents", "tags": [ "documents" ] } }, "/api/v1/apps/{appId}/consent": { "get": { "description": "What the app asks the user to approve: its name, publisher, version and scopes, from the manifest the node installed. Needs no sign-in.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "app_id": { "type": "string" }, "app_name": { "type": "string" }, "publisher": { "type": "string" }, "scopes": { "items": { "properties": { "description": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "description" ], "type": "object" }, "type": "array" }, "version": { "type": "string" } }, "required": [ "app_id", "app_name", "publisher", "version", "scopes" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "What the manifest asks for", "tags": [ "apps" ] } }, "/api/v1/apps/{appId}/grants": { "post": { "description": "Approves the app for the signed-in user and issues its tokens, from the consent ticket the sign-in page gave and, for a PKCE sign-in, the code verifier.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "code_verifier": { "type": "string" }, "consent_ticket": { "type": "string" } }, "required": [ "consent_ticket" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } }, "required": [ "access_token", "refresh_token", "expires_in", "token_type" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, {} ], "summary": "Approve consent and issue tokens", "tags": [ "apps" ] } }, "/api/v1/apps/{appId}/indexes/{index}/vectors/{id}": { "delete": { "description": "Deletes a vector.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Delete a vector", "tags": [ "vectors" ] } }, "/api/v1/apps/{appId}/indexes/{index}/vectors:query": { "post": { "description": "The k nearest vectors to the one given (k defaults to 10, at most 1000), by the index's metric, among those the caller may read, with an optional filter on their metadata.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "filter": { "properties": { "and": { "items": { "description": "recursive", "type": "object" }, "type": "array" }, "field": { "type": "string" }, "not": { "description": "recursive", "type": "object" }, "op": { "type": "string" }, "or": { "items": { "description": "recursive", "type": "object" }, "type": "array" }, "value": {} }, "type": "object" }, "include": { "items": { "type": "string" }, "type": "array" }, "k": { "type": "integer" }, "vector": { "items": { "type": "number" }, "type": "array" } }, "required": [ "vector" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "matches": { "items": { "properties": { "distance": { "type": "number" }, "id": { "type": "string" }, "metadata": { "type": "object" }, "ref": { "type": "string" } }, "required": [ "id", "distance", "ref" ], "type": "object" }, "type": "array" } }, "required": [ "matches" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Top-k vector search", "tags": [ "vectors" ] } }, "/api/v1/apps/{appId}/indexes/{index}/vectors:upsert": { "post": { "description": "Stores a vector, with optional metadata, replacing any vector with the same id. Its length must be the index's dimensions. The app provides the embeddings; the node computes none.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "type": "string" }, "metadata": { "type": "object" }, "ref": { "type": "string" }, "vector": { "items": { "type": "number" }, "type": "array" } }, "required": [ "vector" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Insert or replace a vector", "tags": [ "vectors" ] } }, "/api/v1/apps/{appId}/session": { "get": { "description": "Who the app is signed in as, on which node, and the app as the node installed it.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "app": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "id", "name", "version" ], "type": "object" }, "node": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "name", "url" ], "type": "object" }, "user": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" } }, "required": [ "user", "node", "app" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Who is signed in, on which node, in which app", "tags": [ "apps" ] } }, "/api/v1/apps/{appId}/tables/{table}/rows": { "get": { "description": "A page of the rows the caller may read. Query parameters: limit (default 50, at most 1000) and cursor (the next value of the page before).", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "next": { "type": "string" }, "rows": { "items": { "type": "object" }, "type": "array" } }, "required": [ "rows" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "List table rows (keyset page)", "tags": [ "tables" ] }, "post": { "description": "Creates a row from values: column name to value, checked against the manifest's columns. The caller owns the row.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "values": { "type": "object" } }, "required": [ "values" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Create a table row", "tags": [ "tables" ] } }, "/api/v1/apps/{appId}/tables/{table}/rows/{id}": { "delete": { "description": "Deletes a row the caller may delete.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Delete a row", "tags": [ "tables" ] }, "get": { "description": "One row, with its version.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "One table row", "tags": [ "tables" ] }, "patch": { "description": "Changes some of a row's values. It needs the version the caller last read, in the body or as If-Match; a row changed since, or not there, answers 409.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "values": { "type": "object" }, "version": { "type": "integer" } }, "required": [ "values" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Patch a row (version-checked)", "tags": [ "tables" ] } }, "/api/v1/apps/{appId}/tables/{table}/rows:batch": { "post": { "description": "Up to 100 row writes (create, update with its version, delete) applied together: all of them, or none.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "ops": { "items": { "properties": { "id": { "type": "string" }, "op": { "type": "string" }, "values": { "type": "object" }, "version": { "type": "integer" } }, "required": [ "op" ], "type": "object" }, "type": "array" } }, "required": [ "ops" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "results": { "items": { "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "row": { "type": "object" } }, "required": [ "index", "id" ], "type": "object" }, "type": "array" } }, "required": [ "results" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Atomic batch of row writes", "tags": [ "tables" ] } }, "/api/v1/apps/{appId}/tables/{table}/rows:query": { "post": { "description": "Rows matching a filter (eq, ne, lt, lte, gt, gte, in, nin, combined with and, or and not), with a sort, the fields to select, a limit (default 50, at most 1000) and a cursor. Values are always sent as values: no SQL from a client reaches the database.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "cursor": { "type": "string" }, "filter": { "properties": { "and": { "items": { "description": "recursive", "type": "object" }, "type": "array" }, "field": { "type": "string" }, "not": { "description": "recursive", "type": "object" }, "op": { "type": "string" }, "or": { "items": { "description": "recursive", "type": "object" }, "type": "array" }, "value": {} }, "type": "object" }, "limit": { "type": "integer" }, "select": { "items": { "type": "string" }, "type": "array" }, "sort": { "items": { "properties": { "dir": { "type": "string" }, "field": { "type": "string" } }, "required": [ "field", "dir" ], "type": "object" }, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "next": { "type": "string" }, "rows": { "items": { "type": "object" }, "type": "array" } }, "required": [ "rows" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] }, { "apiToken": [] }, { "appToken": [] } ], "summary": "Query table rows", "tags": [ "tables" ] } }, "/api/v1/auth/account/delete": { "post": { "description": "Closes the account and signs it out. It needs the password. The account and its data are removed when the grace period ends (deleteAfter in the response); until then, the link mailed to the account (when the node can send mail) keeps it. The owner's account cannot be closed: transfer ownership first.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "password": { "type": "string" } }, "required": [ "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleteAfter": { "type": "string" } }, "required": [ "deleteAfter" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Close the account and schedule its deletion", "tags": [ "auth" ] } }, "/api/v1/auth/account/keep": { "post": { "description": "Cancels a scheduled deletion, from the link mailed when the account was closed.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Cancel a scheduled deletion", "tags": [ "auth" ] } }, "/api/v1/auth/app/login": { "post": { "description": "An app signs a user in with email and password and gets a token pair. Off unless the node's admin turns it on (CLOUDOAK_APP_PASSWORD_LOGIN=on): apps normally sign users in on the node's own page (/oauth/authorize), so the password never reaches the app.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "app_id": { "type": "string" }, "code_challenge": { "type": "string" }, "device_label": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "app_id", "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } }, "required": [ "access_token", "refresh_token", "expires_in", "token_type" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "App password grant (off unless CLOUDOAK_APP_PASSWORD_LOGIN=on)", "tags": [ "auth" ] } }, "/api/v1/auth/app/logout": { "post": { "description": "Revokes a refresh token's family: the app is signed out on that device.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Revoke an app refresh family", "tags": [ "auth" ] } }, "/api/v1/auth/app/refresh": { "post": { "description": "Swaps an app's refresh token for a new pair. Each refresh token works once; reusing one revokes its whole family.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } }, "required": [ "access_token", "refresh_token", "expires_in", "token_type" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Rotate an app refresh token", "tags": [ "auth" ] } }, "/api/v1/auth/config": { "get": { "description": "What the sign-in pages need before anyone signs in: the node's name and edition, its registration policy, whether it can send mail, and its billing mode.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "billingMode": { "type": "string" }, "edition": { "type": "string" }, "mail": { "type": "boolean" }, "nodeName": { "type": "string" }, "registration": { "type": "string" } }, "required": [ "registration", "billingMode", "nodeName", "mail", "edition" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Public auth configuration", "tags": [ "auth" ] } }, "/api/v1/auth/email/change": { "post": { "description": "Starts a change of the account's address. It needs the current password, and mails a confirmation link to the new address; nothing changes until that link is used.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "newEmail": { "type": "string" }, "password": { "type": "string" } }, "required": [ "newEmail", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Ask to change the account's email address", "tags": [ "auth" ] } }, "/api/v1/auth/email/change/confirm": { "post": { "description": "Finishes an address change from the link mailed to the new address.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Confirm a new email address", "tags": [ "auth" ] } }, "/api/v1/auth/email/verify": { "post": { "description": "Confirms a new account's address from the link mailed to it.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Confirm a new account's address", "tags": [ "auth" ] } }, "/api/v1/auth/email/verify/resend": { "post": { "description": "Mails the confirmation link again. It answers the same whether or not the address has an account waiting.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Send the confirmation link again", "tags": [ "auth" ] } }, "/api/v1/auth/invitations/accept": { "post": { "description": "Creates the account an admin invited, from the invitation's token, and signs it in.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "password": { "type": "string" }, "token": { "type": "string" }, "username": { "type": "string" } }, "required": [ "token", "username", "name", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrfToken": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "email", "username", "name", "role", "status", "createdAt" ], "type": "object" } }, "required": [ "user", "csrfToken" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Accept an invitation", "tags": [ "auth" ] } }, "/api/v1/auth/invitations/inspect": { "post": { "description": "What an invitation's token is for (the node, the address, the role, who invited it and when the invitation expires), so the page can show it before the account is created.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "email": { "type": "string" }, "expiresAt": { "type": "string" }, "invitedBy": { "type": "string" }, "node": { "type": "string" }, "role": { "type": "string" } }, "required": [ "node", "email", "role", "invitedBy", "expiresAt" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "What an invitation link is for", "tags": [ "auth" ] } }, "/api/v1/auth/login": { "post": { "description": "Signs in to the console with email and password and sets the session cookie. Every later write in that session sends the CSRF token from the response as X-CSRF-Token. Attempts are rate limited.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrfToken": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "email", "username", "name", "role", "status", "createdAt" ], "type": "object" } }, "required": [ "user", "csrfToken" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Sign in with email and password", "tags": [ "auth" ] } }, "/api/v1/auth/logout": { "post": { "description": "Ends this console session and clears its cookie.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Sign out this session", "tags": [ "auth" ] } }, "/api/v1/auth/me": { "get": { "description": "The signed-in account: id, email, username, display name and role.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrfToken": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "email", "username", "name", "role", "status", "createdAt" ], "type": "object" } }, "required": [ "user", "csrfToken" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Current account", "tags": [ "auth" ] }, "patch": { "description": "Changes the username, the display name, or both. A field left out keeps its value.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "username": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrfToken": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "email", "username", "name", "role", "status", "createdAt" ], "type": "object" } }, "required": [ "user", "csrfToken" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Update username and display name", "tags": [ "auth" ] } }, "/api/v1/auth/owner/candidates": { "get": { "description": "The admins the node's owner can hand the node to. Only the owner may call it.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "candidates": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "username", "name" ], "type": "object" }, "type": "array" } }, "required": [ "candidates" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Admins the owner can hand the node to", "tags": [ "auth" ] } }, "/api/v1/auth/owner/transfer": { "post": { "description": "Makes another admin the node's owner. Only the owner may call it, with their password.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "password": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "userId", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Transfer ownership of the node to an admin", "tags": [ "auth" ] } }, "/api/v1/auth/password-reset/confirm": { "post": { "description": "Sets a new password from a reset link's token, which works once. Everything that could act as the account ends: console sessions, API tokens and apps' sign-ins.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "newPassword": { "type": "string" }, "token": { "type": "string" } }, "required": [ "token", "newPassword" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Confirm a password reset", "tags": [ "auth" ] } }, "/api/v1/auth/password-reset/request": { "post": { "description": "Mails a password-reset link to the address, if an account has it. It answers the same either way, so it does not reveal which addresses have accounts. A node that cannot send mail answers 503: there, an admin resets passwords.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Request a password reset", "tags": [ "auth" ] } }, "/api/v1/auth/password/change": { "post": { "description": "Changes the password. It needs the current one. Everything else that could act as the account ends (other console sessions, API tokens, apps' sign-ins); this session stays signed in.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "current": { "type": "string" }, "new": { "type": "string" } }, "required": [ "current", "new" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Change the current password", "tags": [ "auth" ] } }, "/api/v1/auth/register": { "post": { "description": "Creates an account, when the node's registration policy allows it: `open` lets anyone register, `allowlist` only the addresses an admin listed, and `closed` nobody. A new account may have to confirm its address before it can sign in.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" }, "username": { "type": "string" } }, "required": [ "email", "username", "name", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrfToken": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "email", "username", "name", "role", "status", "createdAt" ], "type": "object" } }, "required": [ "user", "csrfToken" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Register an account (policy permitting)", "tags": [ "auth" ] } }, "/api/v1/auth/sessions": { "delete": { "description": "Ends everything that can act as the account: every console session (this one included), every API token, and every app's sign-in on every device. Apps' access tokens stop working on their next request.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Sign out everywhere", "tags": [ "auth" ] } }, "/api/v1/me/credits": { "get": { "description": "The account's credit balance and its latest ledger entries. Query parameter: before, to page back through older entries.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "available": { "type": "integer" }, "balance": { "type": "integer" }, "billingMode": { "type": "string" }, "entries": { "items": { "properties": { "amount": { "type": "integer" }, "createdAt": { "type": "string" }, "id": { "type": "integer" }, "kind": { "type": "string" }, "meter": { "type": "string" } }, "required": [ "id", "kind", "amount", "createdAt" ], "type": "object" }, "type": "array" }, "next": { "type": "string" }, "rates": { "items": { "properties": { "creditsPerUnit": { "type": "integer" }, "meter": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "meter", "unit", "creditsPerUnit" ], "type": "object" }, "type": "array" }, "reserved": { "type": "integer" }, "writeCost": { "type": "integer" } }, "required": [ "billingMode", "balance", "reserved", "available", "writeCost", "rates", "entries", "next" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "My credit balance and latest entries", "tags": [ "account" ] } }, "/api/v1/me/export/{appId}": { "get": { "description": "Everything the signed-in account owns in one app, as JSON lines: a header, a line for each row, and a line for each file with a download link. It is what a user takes with them, for example before closing their account.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Export everything the account owns in one app (JSON lines)", "tags": [ "auth" ] } }, "/api/v1/me/grants": { "get": { "description": "The apps the account has approved.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "My connected apps", "tags": [ "apps" ] } }, "/api/v1/me/grants/{id}": { "delete": { "description": "Revokes an app's grant: its tokens stop working on the next request.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Revoke a grant", "tags": [ "apps" ] } }, "/api/v1/me/usage": { "get": { "description": "What the account used, by app, meter and day.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "apps": { "items": { "properties": { "appId": { "type": "string" }, "appName": { "type": "string" }, "daily": { "items": { "properties": { "day": { "type": "string" }, "meter": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "day", "meter", "quantity" ], "type": "object" }, "type": "array" }, "totals": { "type": "object" } }, "required": [ "appId", "appName", "totals", "daily" ], "type": "object" }, "type": "array" }, "days": { "type": "integer" }, "notMeasured": { "type": "string" } }, "required": [ "days", "apps", "notMeasured" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "My usage by app, meter and day", "tags": [ "account" ] } }, "/api/v1/openapi.json": { "get": { "description": "This document, as the node serves it. Needs no sign-in.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "OpenAPI document for this node", "tags": [ "system" ] } }, "/api/v1/setup": { "post": { "description": "Claims a new node: creates the owner account with the one-time token from the setup link (`cloudoak setup-link`), and signs it in.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" }, "token": { "type": "string" }, "username": { "type": "string" } }, "required": [ "token", "email", "username", "name", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "csrfToken": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "email", "username", "name", "role", "status", "createdAt" ], "type": "object" } }, "required": [ "user", "csrfToken" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Claim the owner account with a setup token", "tags": [ "system" ] } }, "/api/v1/setup/status": { "get": { "description": "Whether the node has an owner yet. Needs no sign-in.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "initialized": { "type": "boolean" } }, "required": [ "initialized" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "First-run setup state", "tags": [ "system" ] } }, "/api/v1/tokens": { "get": { "description": "The account's API tokens: name, scopes, when each was made and when it expires. Never the secrets.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "tokens": { "items": { "properties": { "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "name", "scopes", "createdAt", "expiresAt" ], "type": "object" }, "type": "array" } }, "required": [ "tokens" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "List my API tokens", "tags": [ "account" ] }, "post": { "description": "Makes an API token (oak_pat_...) for scripts. Its scopes are data:read, data:write, app:\u003capp-id\u003e:read or app:\u003capp-id\u003e:write. A token reaches the account's own data in apps and no more, and never the account itself. The secret is in this response only.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "expiresAt": { "type": "string" }, "name": { "type": "string" }, "scopes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name", "scopes" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" }, "tokenResponse": { "properties": { "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "name", "scopes", "createdAt", "expiresAt" ], "type": "object" } }, "required": [ "tokenResponse", "token" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Mint an API token", "tags": [ "account" ] } }, "/api/v1/tokens/{id}": { "delete": { "description": "Revokes an API token. Requests made with it fail from then on.", "responses": { "200": { "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "security": [ { "sessionCookie": [] } ], "summary": "Revoke an API token", "tags": [ "account" ] } }, "/api/v1/version": { "get": { "description": "The node's name, version, licence and public address. Needs no sign-in.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "license": { "type": "string" }, "name": { "type": "string" }, "nodeUrl": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version", "license", "nodeUrl" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Not found" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "Rate limited" } }, "summary": "Node version and license", "tags": [ "system" ] } } } }