{ "openapi": "3.1.0", "info": { "title": "Herald API", "version": "0.3.0-beta.6", "description": "The human-in-the-loop inbox for agents. Guides: https://herald.run/docs/" }, "servers": [ { "url": "https://app.herald.run" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Messages" }, { "name": "Tasks" }, { "name": "Destinations" }, { "name": "Files" }, { "name": "Account" }, { "name": "Connections" }, { "name": "Encryption" } ], "paths": { "/api/ping": { "get": { "operationId": "getApiPing", "summary": "Liveness and server version", "tags": [ "Account" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ping" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/token": { "get": { "operationId": "getToken", "summary": "The calling token, its scopes and account", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenInfo" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteToken", "summary": "Revoke the calling token", "tags": [ "Account" ], "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account": { "get": { "operationId": "getAccount", "summary": "Plan, usage and reset date", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchAccount", "summary": "Rename the account", "tags": [ "Account" ], "description": "Human session only (web or native app); integration tokens get 403.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAccount", "summary": "Delete the account and all its data", "tags": [ "Account" ], "description": "Human session only (web or native app); integration tokens get 403.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "string" } }, "required": [ "confirm" ] } } } }, "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/export": { "get": { "operationId": "getAccountExport", "summary": "Download every account record as JSON", "tags": [ "Account" ], "description": "Human session only (web or native app); integration tokens get 403.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages": { "post": { "operationId": "postMessages", "summary": "Send a message, request or form", "tags": [ "Messages" ], "x-herald-scope": "messages:send", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical request; retries reuse it", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SealedMessageInput" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getMessages", "summary": "List messages (newest first) or the revision feed", "tags": [ "Messages" ], "x-herald-scope": "messages:read", "parameters": [ { "name": "before", "in": "query", "description": "Older page: createdAt|id", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Sender name search", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Revision feed: changes after N, ascending", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "inbound or outbound", "schema": { "type": "string" } }, { "name": "exclude", "in": "query", "description": "true inverts status/direction", "schema": { "type": "string" } }, { "name": "tombstones", "in": "query", "description": "1 includes deletions in the feed", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/Tombstone" } ] } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}": { "get": { "operationId": "getMessagesById", "summary": "A full message or task", "tags": [ "Messages" ], "x-herald-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "patchMessagesById", "summary": "Human: mark read", "tags": [ "Messages" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "read": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteMessagesById", "summary": "Human: delete content and unshared files", "tags": [ "Messages" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}/cancel": { "post": { "operationId": "postMessagesByIdCancel", "summary": "Cancel a pending request", "tags": [ "Messages" ], "x-herald-scope": "messages:send", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}/thread": { "get": { "operationId": "getMessagesByIdThread", "summary": "Thread messages, oldest first, 100 per page", "tags": [ "Messages" ], "x-herald-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Page cursor (start at 0)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "next": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "messages" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}/logs": { "get": { "operationId": "getMessagesByIdLogs", "summary": "Task logs", "tags": [ "Messages" ], "x-herald-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Sequence to start after", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/TaskLog" } } }, "required": [ "logs" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}/response": { "post": { "operationId": "postMessagesByIdResponse", "summary": "Answer a request once", "tags": [ "Messages" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SealedResponseInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}/secrets": { "post": { "operationId": "postMessagesByIdSecrets", "summary": "Collect sealed secret answers once (15 min)", "tags": [ "Messages" ], "x-herald-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SealedEnvelope" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}/secret-receiver": { "get": { "operationId": "getMessagesByIdSecretReceiver", "summary": "Sender: the human device waiting for a secret", "tags": [ "Messages" ], "x-herald-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "claimId": { "type": "string" }, "publicKey": { "$ref": "#/components/schemas/PublicKey" }, "sig": { "type": "string" }, "received": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postMessagesByIdSecretReceiver", "summary": "Human: claim a secret offer with a device key", "tags": [ "Messages" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claimId": { "type": "string" }, "publicKey": { "$ref": "#/components/schemas/PublicKey" }, "sig": { "type": "string" } }, "required": [ "claimId", "publicKey", "sig" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}/secret-delivery": { "post": { "operationId": "postMessagesByIdSecretDelivery", "summary": "Sender: deliver the encrypted secret", "tags": [ "Messages" ], "x-herald-scope": "messages:send", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claimId": { "type": "string" }, "envelope": { "$ref": "#/components/schemas/Envelope" } }, "required": [ "claimId", "envelope" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/{id}/secret-receive": { "post": { "operationId": "postMessagesByIdSecretReceive", "summary": "Human: consume the delivered secret", "tags": [ "Messages" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claimId": { "type": "string" } }, "required": [ "claimId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "envelope": { "$ref": "#/components/schemas/Envelope" }, "pending": { "type": "boolean", "const": true } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/messages/sync": { "post": { "operationId": "postMessagesSync", "summary": "Human: current records for up to 100 IDs", "tags": [ "Messages" ], "description": "Human session only (web or native app); integration tokens get 403.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "maxItems": 100, "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/outbox": { "post": { "operationId": "postOutbox", "summary": "Human: dispatch a task to a destination", "tags": [ "Tasks" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical request; retries reuse it", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SealedOutboxInput" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tasks/{id}/claim": { "post": { "operationId": "postTasksByIdClaim", "summary": "Pull runner: claim a queued task", "tags": [ "Tasks" ], "x-herald-scope": "messages:send", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runnerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "heartbeat": { "type": "boolean" } }, "required": [ "runnerId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "lease": { "type": "string" }, "leaseExpiresAt": { "type": "string" }, "task": { "$ref": "#/components/schemas/Message" } }, "required": [ "lease", "task" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tasks/{id}/heartbeat": { "post": { "operationId": "postTasksByIdHeartbeat", "summary": "Pull runner: renew the lease (every 60 s)", "tags": [ "Tasks" ], "x-herald-scope": "messages:send", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lease": { "type": "string" } }, "required": [ "lease" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "lease": { "type": "string" }, "leaseExpiresAt": { "type": "string" } }, "required": [ "lease" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tasks/{id}/update": { "post": { "operationId": "postTasksByIdUpdate", "summary": "Runner: append logs, complete or fail", "tags": [ "Tasks" ], "x-herald-scope": "messages:send", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lease": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "errorSealed": { "$ref": "#/components/schemas/SealedEnvelope" }, "logs": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stream": { "type": "string", "enum": [ "stdout", "stderr" ] }, "text": { "type": "string", "const": "" }, "sealed": { "$ref": "#/components/schemas/SealedEnvelope" } }, "required": [ "sequence", "stream", "sealed" ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/destinations": { "get": { "operationId": "getDestinations", "summary": "List destinations", "tags": [ "Destinations" ], "x-herald-scope": "destinations:manage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Destination" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postDestinations", "summary": "Register a destination; a repeated key updates it", "tags": [ "Destinations" ], "x-herald-scope": "destinations:manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationInput" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/destinations/{id}": { "put": { "operationId": "putDestinationsById", "summary": "Replace a destination", "tags": [ "Destinations" ], "x-herald-scope": "destinations:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteDestinationsById", "summary": "Remove a destination and cancel its queued tasks", "tags": [ "Destinations" ], "x-herald-scope": "destinations:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/destinations/{id}/secret": { "post": { "operationId": "postDestinationsByIdSecret", "summary": "Rotate a webhook signing secret (returned once)", "tags": [ "Destinations" ], "x-herald-scope": "destinations:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/files": { "post": { "operationId": "postFiles", "summary": "Reserve an upload (≤100 MB, 15 min)", "tags": [ "Files" ], "x-herald-scope": "files:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "const": "encrypted" }, "type": { "type": "string", "const": "application/octet-stream" }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000000 } }, "required": [ "name", "type", "size" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/files/{id}": { "put": { "operationId": "putFilesById", "summary": "Upload the exact reserved bytes once", "tags": [ "Files" ], "x-herald-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getFilesById", "summary": "Download a file", "tags": [ "Files" ], "x-herald-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/integrations": { "get": { "operationId": "getIntegrations", "summary": "List connections", "tags": [ "Connections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postIntegrations", "summary": "Create a connection; the token is returned once", "tags": [ "Connections" ], "description": "Human session only (web or native app); integration tokens get 403.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "messages:send", "messages:read", "destinations:manage", "events:read", "files:write" ] } }, "certificate": { "$ref": "#/components/schemas/Certificate" } }, "required": [ "name", "scopes", "certificate" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "integration": { "$ref": "#/components/schemas/Integration" } }, "required": [ "token", "integration" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/integrations/{id}": { "patch": { "operationId": "patchIntegrationsById", "summary": "Rename or recolor a connection", "tags": [ "Connections" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "$ref": "#/components/schemas/ConnectionColor" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteIntegrationsById", "summary": "Revoke a connection and its destinations", "tags": [ "Connections" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys": { "get": { "operationId": "getKeys", "summary": "The account statement and connection certificates", "tags": [ "Encryption" ], "x-herald-scope": "messages:read", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyDirectory" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/account": { "put": { "operationId": "putKeysAccount", "summary": "Publish the account statement (201 new, 200 same identity)", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeys" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeys" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteKeysAccount", "summary": "Turn end-to-end encryption off and delete every key record", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "string" } }, "required": [ "confirm" ] } } } }, "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/backups": { "get": { "operationId": "getKeysBackups", "summary": "Wrapped keyring backups", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "backups": { "type": "array", "items": { "$ref": "#/components/schemas/KeyBackup" } } }, "required": [ "backups" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/backups/{id}": { "put": { "operationId": "putKeysBackupsById", "summary": "Store a wrapped keyring (at most 10)", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wrapped": { "$ref": "#/components/schemas/WrappedKeyring" } }, "required": [ "wrapped" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyBackup" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteKeysBackupsById", "summary": "Delete a backup", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/device-code/{code}": { "put": { "operationId": "putKeysDeviceCodeByCode", "summary": "Certify CLI keys for a device user code (15 min)", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getKeysDeviceCodeByCode", "summary": "CLI: fetch its certificate once", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/devices": { "post": { "operationId": "postKeysDevices", "summary": "Locked device: ask another device for the keyring (15 min)", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "commit": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "label", "commit" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingDevice" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getKeysDevices", "summary": "Devices waiting for approval", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/PendingDevice" } } }, "required": [ "devices" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/devices/{id}": { "get": { "operationId": "getKeysDevicesById", "summary": "A pending device; the envelope once approved", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "consume", "in": "query", "description": "1 deletes an approved or rejected record", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingDevice" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteKeysDevicesById", "summary": "Reject a pending device; again to remove it", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/devices/{id}/challenge": { "post": { "operationId": "postKeysDevicesByIdChallenge", "summary": "Approver: send a nonce (waiting → challenged)", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "nonce" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingDevice" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/devices/{id}/reveal": { "post": { "operationId": "postKeysDevicesByIdReveal", "summary": "Locked device: open the commitment (challenged → revealed)", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "nonce": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "transfer", "nonce" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingDevice" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys/devices/{id}/approve": { "post": { "operationId": "postKeysDevicesByIdApprove", "summary": "Approver: send the keyring envelope (revealed → approved)", "tags": [ "Encryption" ], "description": "Human session only (web or native app); integration tokens get 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "envelope": { "$ref": "#/components/schemas/SealedEnvelope" } }, "required": [ "envelope" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingDevice" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/ws-ticket": { "post": { "operationId": "postWsTicket", "summary": "One-time socket ticket (30 s)", "tags": [ "Connections" ], "description": "Human session only (web or native app); integration tokens get 403.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "string" } }, "required": [ "ticket" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope, human session or admission (NOT_ADMITTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict, such as a changed idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Expired or already consumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; wait Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Integration token (hdr_…) from Settings → Connections or herald login" } }, "schemas": { "MessageInput": { "$id": "#/components/schemas/MessageInput", "oneOf": [ { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "body": { "default": "", "type": "string", "maxLength": 50000 }, "runId": { "type": "string", "maxLength": 120 }, "checkpointId": { "type": "string", "maxLength": 120 }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replyTo": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requiresReview": { "type": "boolean" }, "group": { "type": "string", "maxLength": 120 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expiresIn": { "type": "number", "exclusiveMinimum": 0, "maximum": 86400 }, "kind": { "default": "message", "type": "string", "enum": [ "message", "form", "report", "files" ] }, "fields": { "default": [], "maxItems": 30, "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "questions": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 300 }, "header": { "type": "string", "minLength": 1, "maxLength": 24 }, "options": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 300 }, "preview": { "type": "string", "maxLength": 4000 } }, "required": [ "label" ] } }, "multiSelect": { "default": false, "type": "boolean" } }, "required": [ "question", "options" ] } }, "blocks": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/ReviewBlock" } }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "$ref": "#/components/schemas/Action" } }, "attachments": { "default": [], "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "publicKey": { "$ref": "#/components/schemas/PublicKey" } }, "required": [ "title" ] }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "body": { "default": "", "type": "string", "maxLength": 50000 }, "runId": { "type": "string", "maxLength": 120 }, "checkpointId": { "type": "string", "maxLength": 120 }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replyTo": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requiresReview": { "type": "boolean" }, "group": { "type": "string", "maxLength": 120 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expiresIn": { "type": "number", "exclusiveMinimum": 0, "maximum": 86400 }, "kind": { "type": "string", "const": "secret" }, "fields": {}, "attachments": {}, "schema": {}, "questions": {}, "blocks": {}, "actions": {}, "publicKey": {} }, "required": [ "title", "kind" ] } ] }, "Field": { "$id": "#/components/schemas/Field", "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "header": { "type": "string", "minLength": 1, "maxLength": 24 }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select", "multiselect", "boolean", "date", "secret", "file" ] }, "default": { "anyOf": [ { "type": "string", "maxLength": 16000 }, { "type": "number" }, { "type": "boolean" }, { "maxItems": 50, "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "nullable": { "type": "boolean" }, "uniqueItems": { "type": "boolean" }, "integer": { "type": "boolean" }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "exclusiveMinimum": { "type": "number" }, "exclusiveMaximum": { "type": "number" }, "minLength": { "type": "integer", "minimum": 0, "maximum": 16000 }, "maxLength": { "type": "integer", "minimum": 0, "maximum": 16000 }, "minItems": { "type": "integer", "minimum": 0, "maximum": 50 }, "maxItems": { "type": "integer", "minimum": 0, "maximum": 50 }, "required": { "default": false, "type": "boolean" }, "secret": { "type": "boolean" }, "help": { "type": "string", "maxLength": 300 }, "placeholder": { "type": "string", "maxLength": 120 }, "options": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "maxLength": 100 }, "label": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 300 }, "preview": { "type": "string", "maxLength": 4000 } }, "required": [ "value", "label" ] } }, "other": { "type": "boolean" } }, "required": [ "id", "label", "type" ] }, "Action": { "$id": "#/components/schemas/Action", "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "values": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 16000 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 100 } } ] } } }, "required": [ "id", "label", "values" ], "additionalProperties": false }, "ReviewBlock": { "$id": "#/components/schemas/ReviewBlock", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "code", "diff", "json" ] }, "title": { "type": "string", "maxLength": 180 }, "requiresReview": { "type": "boolean" }, "language": { "default": "text", "type": "string", "enum": [ "text", "sql", "javascript", "typescript", "python", "json" ] }, "text": { "type": "string", "maxLength": 50000 } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "table" }, "title": { "type": "string", "maxLength": 180 }, "requiresReview": { "type": "boolean" }, "columns": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "rows": { "maxItems": 100, "type": "array", "items": { "maxItems": 12, "type": "array", "items": { "type": "string", "maxLength": 2000 } } } }, "required": [ "type", "columns", "rows" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "title": { "type": "string", "maxLength": 180 }, "requiresReview": { "type": "boolean" }, "attachmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "alt": { "type": "string", "maxLength": 500 } }, "required": [ "type", "attachmentId", "alt" ], "additionalProperties": false } ] }, "Attachment": { "$id": "#/components/schemas/Attachment", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "maxLength": 200 }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "type": { "type": "string", "maxLength": 120 } }, "required": [ "id", "name", "size", "type" ] }, "PublicKey": { "$id": "#/components/schemas/PublicKey", "type": "object", "properties": { "kty": { "type": "string", "const": "RSA" }, "n": { "type": "string", "minLength": 300, "maxLength": 1400 }, "e": { "type": "string", "const": "AQAB" }, "alg": { "type": "string", "const": "RSA-OAEP-256" }, "ext": { "type": "boolean" }, "key_ops": { "type": "array", "items": { "type": "string", "const": "encrypt" } } }, "required": [ "kty", "n", "e" ], "additionalProperties": false }, "Envelope": { "$id": "#/components/schemas/Envelope", "type": "object", "properties": { "key": { "type": "string", "maxLength": 1500 }, "iv": { "type": "string", "maxLength": 30 }, "data": { "type": "string", "maxLength": 90000 } }, "required": [ "key", "iv", "data" ], "additionalProperties": false }, "DestinationInput": { "$id": "#/components/schemas/DestinationInput", "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "transport": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "pull" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "kind", "url" ] } ] }, "description": { "default": "", "type": "string", "maxLength": 300 }, "types": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/RequestType" } } }, "required": [ "types" ] }, "RequestType": { "$id": "#/components/schemas/RequestType", "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "default": "", "type": "string", "maxLength": 300 }, "fields": { "default": [], "maxItems": 30, "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "kind": { "type": "string", "const": "session" }, "session": { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "placeholder": { "type": "string", "maxLength": 120 }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 16000 } }, "additionalProperties": false }, "attachments": { "type": "object", "properties": { "maxFiles": { "type": "integer", "minimum": 1, "maximum": 10 } }, "required": [ "maxFiles" ], "additionalProperties": false }, "modes": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 300 }, "options": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "value", "label" ], "additionalProperties": false } }, "default": { "type": "string", "maxLength": 100 }, "id": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,39}$" } }, "required": [ "label", "options", "id" ], "additionalProperties": false } }, "model": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 300 }, "options": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "value", "label" ], "additionalProperties": false } }, "default": { "type": "string", "maxLength": 100 } }, "required": [ "label", "options" ], "additionalProperties": false }, "effort": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 300 }, "options": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "value", "label" ], "additionalProperties": false } }, "default": { "type": "string", "maxLength": 100 } }, "required": [ "label", "options" ], "additionalProperties": false }, "commands": { "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,39}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 300 }, "arguments": { "default": [], "maxItems": 30, "type": "array", "items": { "$ref": "#/components/schemas/Field" } } }, "required": [ "id", "label" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "id", "label" ] }, "SessionInput": { "$id": "#/components/schemas/SessionInput", "type": "object", "properties": { "prompt": { "type": "string", "maxLength": 16000 }, "modes": { "default": {}, "type": "object", "propertyNames": { "type": "string", "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 100 } }, "model": { "type": "string", "maxLength": 100 }, "effort": { "type": "string", "maxLength": 100 }, "command": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 40 }, "arguments": { "default": {}, "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 16000 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 100 } } ] } } }, "required": [ "id" ], "additionalProperties": false }, "attachments": { "maxItems": 10, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "prompt" ], "additionalProperties": false }, "ResponseInput": { "$id": "#/components/schemas/ResponseInput", "type": "object", "properties": { "values": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 16000 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 100 } } ] } }, "actionId": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "secrets": { "default": {}, "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "$ref": "#/components/schemas/Envelope" } } }, "required": [ "values" ] }, "ConnectionColor": { "$id": "#/components/schemas/ConnectionColor", "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "auto" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "neutral" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "custom" }, "hue": { "type": "number", "minimum": 0, "exclusiveMaximum": 360 }, "saturation": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "mode", "hue", "saturation" ], "additionalProperties": false } ] }, "SealedEnvelope": { "$id": "#/components/schemas/SealedEnvelope", "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "ctx": { "type": "object", "properties": { "t": { "type": "string", "minLength": 1, "maxLength": 32 }, "account": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "t", "account" ], "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] } }, "from": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]*$" }, "to": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "kid": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]*$" }, "enc": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "key": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "kid", "enc", "key" ], "additionalProperties": false } }, "iv": { "type": "string", "minLength": 16, "maxLength": 16, "pattern": "^[A-Za-z0-9_-]*$" }, "ct": { "type": "string", "minLength": 22, "maxLength": 180000, "pattern": "^[A-Za-z0-9_-]*$" }, "sig": { "type": "string", "minLength": 86, "maxLength": 86, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "v", "ctx", "from", "to", "iv", "ct", "sig" ], "additionalProperties": false }, "SealedMessageInput": { "$id": "#/components/schemas/SealedMessageInput", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "default": "message", "type": "string", "enum": [ "message", "secret" ] }, "sealed": { "$ref": "#/components/schemas/SealedEnvelope" }, "digest": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "asks": { "type": "boolean" }, "attachments": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ], "additionalProperties": false } }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replyTo": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expiresIn": { "type": "number", "exclusiveMinimum": 0, "maximum": 86400 } }, "required": [ "id", "sealed", "digest", "asks" ], "additionalProperties": false }, "SealedResponseInput": { "$id": "#/components/schemas/SealedResponseInput", "type": "object", "properties": { "sealed": { "$ref": "#/components/schemas/SealedEnvelope" }, "secrets": { "default": {}, "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "$ref": "#/components/schemas/SealedEnvelope" } }, "files": { "default": [], "maxItems": 30, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "secretFiles": { "default": [], "maxItems": 30, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "sealed" ], "additionalProperties": false }, "SealedOutboxInput": { "$id": "#/components/schemas/SealedOutboxInput", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "destinationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "typeId": { "type": "string", "minLength": 1, "maxLength": 64 }, "sealed": { "$ref": "#/components/schemas/SealedEnvelope" }, "files": { "default": [], "maxItems": 30, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "grants": { "default": [], "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kid": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]*$" }, "enc": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "key": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "message", "kid", "enc", "key" ], "additionalProperties": false } }, "replyTo": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expiresIn": { "type": "number", "exclusiveMinimum": 0, "maximum": 86400 } }, "required": [ "id", "destinationId", "typeId", "sealed" ], "additionalProperties": false }, "AccountKeys": { "$id": "#/components/schemas/AccountKeys", "type": "object", "properties": { "statement": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "account": { "type": "string", "minLength": 1, "maxLength": 200 }, "identity": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "inbox": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "created": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "v", "account", "identity", "inbox", "created" ], "additionalProperties": false }, "sig": { "type": "string", "minLength": 86, "maxLength": 86, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "statement", "sig" ], "additionalProperties": false }, "Certificate": { "$id": "#/components/schemas/Certificate", "type": "object", "properties": { "certificate": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "account": { "type": "string", "minLength": 1, "maxLength": 200 }, "kid": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]*$" }, "sign": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "box": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "created": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "v", "account", "kid", "sign", "box", "created" ], "additionalProperties": false }, "sig": { "type": "string", "minLength": 86, "maxLength": 86, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "certificate", "sig" ], "additionalProperties": false }, "WrappedKeyring": { "$id": "#/components/schemas/WrappedKeyring", "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "kind": { "type": "string", "enum": [ "prf", "recovery" ] }, "credentialId": { "type": "string", "maxLength": 1400, "pattern": "^[A-Za-z0-9_-]*$" }, "iv": { "type": "string", "minLength": 16, "maxLength": 16, "pattern": "^[A-Za-z0-9_-]*$" }, "ct": { "type": "string", "maxLength": 20000, "pattern": "^[A-Za-z0-9_-]*$" } }, "required": [ "v", "kind", "iv", "ct" ], "additionalProperties": false }, "Error": { "$id": "#/components/schemas/Error", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} }, "Ping": { "$id": "#/components/schemas/Ping", "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "channel": { "type": "string" }, "version": { "type": "string" } }, "required": [ "ok", "channel", "version" ] }, "Message": { "$id": "#/components/schemas/Message", "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "form", "report", "files", "secret" ] }, "status": { "type": "string", "enum": [ "pending", "answered", "delivered", "expired", "cancelled", "queued", "running", "completed", "failed" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "sender": { "type": "string" }, "senderId": { "type": "string" }, "createdAt": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "read": { "type": "boolean" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewBlock" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } }, "response": { "type": "object", "properties": { "values": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 16000 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 100 } } ] } }, "actionId": { "type": "string" }, "secretFields": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "sealed": { "$ref": "#/components/schemas/SealedEnvelope" } }, "required": [ "values" ], "additionalProperties": {} }, "expiresAt": { "type": "string" }, "replyTo": { "type": "string" }, "threadId": { "type": "string" }, "threadSequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "runId": { "type": "string" }, "secretDelivery": { "type": "string", "enum": [ "offered", "claimed", "ready", "received" ] }, "destinationId": { "type": "string" }, "typeId": { "type": "string" }, "input": { "type": "object", "properties": { "destinationId": { "type": "string" }, "typeId": { "type": "string" }, "values": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 16000 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 100 } } ] } }, "sealed": { "$ref": "#/components/schemas/SealedEnvelope" } }, "required": [ "destinationId", "typeId", "values" ], "additionalProperties": {} }, "result": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ] }, "completedAt": { "type": "string" }, "reason": { "type": "string", "enum": [ "webhook-unavailable", "not-acknowledged", "lease-lapsed" ] }, "sealed": { "$ref": "#/components/schemas/SealedEnvelope" } }, "required": [ "status", "completedAt" ] }, "sealed": { "$ref": "#/components/schemas/SealedEnvelope" } }, "required": [ "id", "title", "kind", "status", "direction", "sender", "createdAt" ], "additionalProperties": {} }, "Tombstone": { "$id": "#/components/schemas/Tombstone", "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "revision", "deleted" ] }, "Destination": { "$id": "#/components/schemas/Destination", "type": "object", "properties": { "id": { "type": "string" }, "integrationId": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string" }, "signingSecret": { "type": "string" } }, "required": [ "id", "integrationId", "name" ], "additionalProperties": {} }, "Account": { "$id": "#/components/schemas/Account", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "plan": { "type": "string" }, "used": { "type": "number" }, "reserved": { "type": "number" }, "credits": { "type": "number" }, "storage": { "type": "number" }, "usageResetsAt": { "type": "string" } }, "required": [ "id", "email", "plan", "used", "storage" ], "additionalProperties": {} }, "Integration": { "$id": "#/components/schemas/Integration", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "messages:send", "messages:read", "destinations:manage", "events:read", "files:write" ] } }, "createdAt": { "type": "string" }, "color": { "$ref": "#/components/schemas/ConnectionColor" }, "e2ee": { "type": "boolean" } }, "required": [ "id", "name", "scopes", "createdAt" ], "additionalProperties": {} }, "TokenInfo": { "$id": "#/components/schemas/TokenInfo", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "messages:send", "messages:read", "destinations:manage", "events:read", "files:write" ] } }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ] }, "account": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "email", "name" ] } }, "required": [ "id", "name", "scopes", "createdAt", "lastUsedAt", "account" ] }, "TaskLog": { "$id": "#/components/schemas/TaskLog", "type": "object", "properties": { "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stream": { "type": "string", "enum": [ "stdout", "stderr" ] }, "text": { "type": "string" }, "sealed": { "$ref": "#/components/schemas/SealedEnvelope" } }, "required": [ "sequence", "stream", "text" ] }, "KeyDirectory": { "$id": "#/components/schemas/KeyDirectory", "type": "object", "properties": { "account": { "anyOf": [ { "$ref": "#/components/schemas/AccountKeys" }, { "type": "null" } ] }, "certificates": { "type": "array", "items": { "type": "object", "properties": { "certificate": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "account": { "type": "string", "minLength": 1, "maxLength": 200 }, "kid": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]*$" }, "sign": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "box": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]*$" }, "created": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "v", "account", "kid", "sign", "box", "created" ], "additionalProperties": false }, "sig": { "type": "string", "minLength": 86, "maxLength": 86, "pattern": "^[A-Za-z0-9_-]*$" }, "integrationId": { "type": "string" } }, "required": [ "certificate", "sig", "integrationId" ], "additionalProperties": false } } }, "required": [ "account", "certificates" ] }, "KeyBackup": { "$id": "#/components/schemas/KeyBackup", "type": "object", "properties": { "id": { "type": "string" }, "wrapped": { "$ref": "#/components/schemas/WrappedKeyring" }, "createdAt": { "type": "string" } }, "required": [ "id", "wrapped", "createdAt" ] }, "PendingDevice": { "$id": "#/components/schemas/PendingDevice", "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "waiting", "challenged", "revealed", "approved", "rejected" ] }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "commit": { "type": "string" }, "challenge": { "type": "string" }, "transfer": { "type": "string" }, "nonce": { "type": "string" }, "envelope": { "$ref": "#/components/schemas/SealedEnvelope" } }, "required": [ "id", "label", "state", "createdAt", "expiresAt", "commit" ] } } } }