{ "openapi": "3.1.0", "info": { "title": "Vellum Gateway API", "version": "0.10.12", "description": "Auto-generated OpenAPI specification for the Vellum Gateway HTTP endpoints." }, "servers": [{ "url": "", "description": "Same-origin (gateway)" }], "paths": { "/v1/permissions/thresholds": { "get": { "operationId": "permissionsThresholdsGet", "summary": "Get global auto-approve thresholds", "tags": ["permissions"], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "interactive": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "autonomous": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "headless": { "type": "string", "enum": ["none", "low", "medium", "high"] } }, "required": ["interactive", "autonomous", "headless"], "additionalProperties": false } } } } } }, "put": { "operationId": "permissionsThresholdsPut", "summary": "Update global auto-approve thresholds", "tags": ["permissions"], "description": "Partial update — omitted modes keep their current value. Returns the full post-update set.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interactive": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "autonomous": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "headless": { "type": "string", "enum": ["none", "low", "medium", "high"] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "interactive": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "autonomous": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "headless": { "type": "string", "enum": ["none", "low", "medium", "high"] } }, "required": ["interactive", "autonomous", "headless"], "additionalProperties": false } } } } } } }, "/v1/permissions/thresholds/conversations/{conversation_id}": { "get": { "operationId": "conversationThresholdGet", "summary": "Get a conversation's threshold override", "tags": ["permissions"], "description": "Returns { threshold: null } when no override exists. (Gateways predating that behavior returned 404 for the same condition; clients tolerate both during rollout.)", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The conversation id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "threshold": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["threshold"], "additionalProperties": false } } } } } }, "put": { "operationId": "conversationThresholdPut", "summary": "Set a conversation's threshold override", "tags": ["permissions"], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The conversation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "threshold": { "type": "string", "enum": ["none", "low", "medium", "high"] } }, "required": ["threshold"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" }, "threshold": { "type": "string", "enum": ["none", "low", "medium", "high"] } }, "required": ["conversationId", "threshold"], "additionalProperties": false } } } } } }, "delete": { "operationId": "conversationThresholdDelete", "summary": "Clear a conversation's threshold override", "tags": ["permissions"], "description": "Idempotent — succeeds even when no override exists.", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The conversation id" } ], "responses": { "204": { "description": "Successful response" } } } }, "/v1/channel-admission-policy": { "get": { "operationId": "channelAdmissionPolicyList", "summary": "List per-channel admission floors", "tags": ["channel-admission-policy"], "description": "Returns one entry per enforced channel (exempt and hidden channels are omitted), seeded with defaults for channels without a stored row.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "items": { "type": "object", "properties": { "channelType": { "type": "string" }, "policy": { "type": "string", "enum": [ "no_one", "guardian_only", "trusted_contacts", "any_contact", "strangers" ] }, "note": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "updatedAt": { "anyOf": [{ "type": "number" }, { "type": "null" }] } }, "required": [ "channelType", "policy", "note", "updatedAt" ], "additionalProperties": false } } }, "required": ["policies"], "additionalProperties": false } } } } } } }, "/v1/channel-admission-policy/{channel_type}": { "put": { "operationId": "channelAdmissionPolicySet", "summary": "Set a channel's admission floor", "tags": ["channel-admission-policy"], "description": "Upserts the channel's admission policy. Exempt and hidden channels return 403.", "parameters": [ { "name": "channel_type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The channel type (e.g. slack)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "string", "enum": [ "no_one", "guardian_only", "trusted_contacts", "any_contact", "strangers" ] }, "note": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["policy"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "channelType": { "type": "string" }, "policy": { "type": "string", "enum": [ "no_one", "guardian_only", "trusted_contacts", "any_contact", "strangers" ] }, "note": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "updatedAt": { "anyOf": [{ "type": "number" }, { "type": "null" }] } }, "required": [ "channelType", "policy", "note", "updatedAt" ], "additionalProperties": false } }, "required": ["policy"], "additionalProperties": false } } } } } } }, "/v1/channel-ingress/{source}/approve": { "post": { "operationId": "channelIngressApprove", "summary": "Approve an ingress declaration", "tags": ["channel-ingress"], "description": "Records the guardian's approval of the declaration identified by the body's digest, after which the gateway serves its routes. Returns 409 when the digest is not what the source currently declares, and 404 when it declares nothing servable.", "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The declaring ingress source (today, a plugin name)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[0-9a-f]{32}$" } }, "required": ["digest"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "digest": { "type": "string" }, "approvedAt": { "type": "number" } }, "required": ["source", "digest", "approvedAt"], "additionalProperties": false } } } } } } }, "/v1/channel-ingress/{source}/revoke": { "post": { "operationId": "channelIngressRevoke", "summary": "Revoke an ingress approval", "tags": ["channel-ingress"], "description": "Withdraws the source's grant, after which its routes stop being served. Reports whether there was a grant to withdraw. Succeeds even when the declaration itself has become unreadable.", "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The declaring ingress source (today, a plugin name)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "revoked": { "type": "boolean" } }, "required": ["source", "revoked"], "additionalProperties": false } } } } } } }, "/v1/channel-permission-overrides": { "get": { "operationId": "channelPermissionOverridesList", "summary": "List channel-permission matrix cells", "tags": ["channel-permission-overrides"], "description": "Returns every persisted cell (cascade selector × contact-type → RiskThreshold). Unset cells fall through the cascade; the list contains only explicit overrides.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cells": { "type": "array", "items": { "type": "object", "properties": { "selector": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "workspace" } }, "required": ["scope"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "adapter" }, "adapter": { "type": "string", "minLength": 1 } }, "required": ["scope", "adapter"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "channel_type" }, "adapter": { "type": "string", "minLength": 1 }, "channelType": { "type": "string", "enum": ["dm", "private", "public"] } }, "required": ["scope", "adapter", "channelType"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "channel" }, "adapter": { "type": "string", "minLength": 1 }, "channelExternalId": { "type": "string", "minLength": 1 } }, "required": [ "scope", "adapter", "channelExternalId" ], "additionalProperties": false } ], "type": "object" }, "contactType": { "type": "string", "enum": [ "guardian", "trusted_contact", "unverified_contact", "unknown" ] }, "threshold": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "note": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "updatedAt": { "type": "number" } }, "required": [ "selector", "contactType", "threshold", "updatedAt" ], "additionalProperties": false } } }, "required": ["cells"], "additionalProperties": false } } } } } }, "put": { "operationId": "channelPermissionOverrideSet", "summary": "Upsert a channel-permission matrix cell", "tags": ["channel-permission-overrides"], "description": "Upserts one cell, identified by the selector × contact-type in the body. The adapter must be a known channel id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selector": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "workspace" } }, "required": ["scope"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "adapter" }, "adapter": { "type": "string", "minLength": 1 } }, "required": ["scope", "adapter"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "channel_type" }, "adapter": { "type": "string", "minLength": 1 }, "channelType": { "type": "string", "enum": ["dm", "private", "public"] } }, "required": ["scope", "adapter", "channelType"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "channel" }, "adapter": { "type": "string", "minLength": 1 }, "channelExternalId": { "type": "string", "minLength": 1 } }, "required": ["scope", "adapter", "channelExternalId"], "additionalProperties": false } ], "type": "object" }, "contactType": { "type": "string", "enum": [ "guardian", "trusted_contact", "unverified_contact", "unknown" ] }, "threshold": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "note": { "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["selector", "contactType", "threshold"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cell": { "type": "object", "properties": { "selector": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "workspace" } }, "required": ["scope"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "adapter" }, "adapter": { "type": "string", "minLength": 1 } }, "required": ["scope", "adapter"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "channel_type" }, "adapter": { "type": "string", "minLength": 1 }, "channelType": { "type": "string", "enum": ["dm", "private", "public"] } }, "required": ["scope", "adapter", "channelType"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "channel" }, "adapter": { "type": "string", "minLength": 1 }, "channelExternalId": { "type": "string", "minLength": 1 } }, "required": [ "scope", "adapter", "channelExternalId" ], "additionalProperties": false } ], "type": "object" }, "contactType": { "type": "string", "enum": [ "guardian", "trusted_contact", "unverified_contact", "unknown" ] }, "threshold": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "note": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "updatedAt": { "type": "number" } }, "required": [ "selector", "contactType", "threshold", "updatedAt" ], "additionalProperties": false } }, "required": ["cell"], "additionalProperties": false } } } } } } }, "/v1/channel-permission-overrides/resolve": { "post": { "operationId": "channelPermissionResolve", "summary": "Resolve the effective channel-permission threshold", "tags": ["channel-permission-overrides"], "description": "Read-only cascade resolution for one coordinate: walks channel → channel_type → adapter → workspace for the given selector keys and contact-type, returning the winning cell's threshold and scope, or null when no cell matches (the caller then falls through to the global thresholds). Same resolver the runtime evaluator uses over IPC.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "adapter": { "type": "string", "minLength": 1 }, "channelType": { "type": "string", "enum": ["dm", "private", "public"] }, "channelExternalId": { "type": "string", "minLength": 1 }, "contactType": { "type": "string", "enum": [ "guardian", "trusted_contact", "unverified_contact", "unknown" ] } }, "required": ["adapter", "contactType"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resolved": { "anyOf": [ { "type": "object", "properties": { "threshold": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "scope": { "type": "string", "enum": [ "workspace", "adapter", "channel_type", "channel" ] } }, "required": ["threshold", "scope"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["resolved"], "additionalProperties": false } } } } } } }, "/v1/channel-permission-overrides/delete": { "post": { "operationId": "channelPermissionOverrideDelete", "summary": "Delete a channel-permission matrix cell", "tags": ["channel-permission-overrides"], "description": "Removes one cell by its composite key (selector × contact-type), letting the next cascade tier up win. Returns whether a cell was removed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selector": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "workspace" } }, "required": ["scope"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "adapter" }, "adapter": { "type": "string", "minLength": 1 } }, "required": ["scope", "adapter"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "channel_type" }, "adapter": { "type": "string", "minLength": 1 }, "channelType": { "type": "string", "enum": ["dm", "private", "public"] } }, "required": ["scope", "adapter", "channelType"], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "channel" }, "adapter": { "type": "string", "minLength": 1 }, "channelExternalId": { "type": "string", "minLength": 1 } }, "required": ["scope", "adapter", "channelExternalId"], "additionalProperties": false } ], "type": "object" }, "contactType": { "type": "string", "enum": [ "guardian", "trusted_contact", "unverified_contact", "unknown" ] } }, "required": ["selector", "contactType"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": ["removed"], "additionalProperties": false } } } } } } }, "/v1/contacts": { "post": { "operationId": "contactsUpsert", "summary": "Create or update a contact", "tags": ["contacts"], "description": "Gateway-native contact upsert (dual-writes the gateway ACL store and the assistant info mirror). Matches by id, then by any provided (type, address) channel, else creates.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Existing contact id to update; omit to create or match by channel", "type": "string" }, "displayName": { "type": "string", "minLength": 1, "description": "Required on every upsert, including updates by id" }, "notes": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "contactType": { "type": "string" }, "assistantMetadata": { "description": "Required when contactType is 'assistant'", "type": "object", "properties": { "species": { "type": "string" }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": ["species"] }, "channels": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "address": { "type": "string" }, "isPrimary": { "type": "boolean" }, "externalChatId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "status": { "type": "string" }, "policy": { "type": "string" } }, "required": ["type", "address"] } } }, "required": ["displayName"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "contact": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "notes": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "contactType": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "principalId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "userFile": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "interactionCount": { "type": "number" }, "lastInteraction": { "anyOf": [{ "type": "number" }, { "type": "null" }] }, "assistantMetadata": { "anyOf": [ { "type": "object", "properties": { "species": { "type": "string" }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": ["species", "metadata"], "additionalProperties": false }, { "type": "null" } ] }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "type": { "type": "string" }, "address": { "type": "string" }, "isPrimary": { "type": "boolean" }, "externalChatId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalUserId": { "type": "string", "description": "Compat alias for address (older macOS clients)" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verifiedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "verifiedVia": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revokedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blockedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSeenAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "interactionCount": { "type": "number" }, "lastInteraction": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "contactId", "type", "address", "isPrimary", "externalChatId", "externalUserId", "status", "policy", "verifiedAt", "verifiedVia", "inviteId", "revokedReason", "blockedReason", "lastSeenAt", "interactionCount", "lastInteraction", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "id", "displayName", "role", "notes", "contactType", "principalId", "userFile", "createdAt", "updatedAt", "interactionCount", "lastInteraction", "assistantMetadata", "channels" ], "additionalProperties": false } }, "required": ["ok", "contact"], "additionalProperties": false } } } } } } }, "/v1/contacts/{contact_id}": { "delete": { "operationId": "contactDelete", "summary": "Delete a contact", "tags": ["contacts"], "description": "Deletes a non-guardian contact from the gateway ACL store and the assistant mirror. 404 when the contact exists in neither; 403 for guardian contacts.", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The contact id" } ], "responses": { "204": { "description": "Successful response" } } } }, "/v1/contacts/prompt/submit": { "post": { "operationId": "contactsPromptSubmit", "summary": "Submit a contact-prompt address", "tags": ["contacts"], "description": "Completes a daemon-broadcast contact_request: writes the contact and channel gateway-first, then unblocks the waiting prompt via daemon IPC.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The contact_request id broadcast by the daemon" }, "address": { "type": "string" }, "channelType": { "type": "string" }, "role": { "type": "string" }, "displayName": { "type": "string" } }, "required": ["requestId", "address", "channelType"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "error": { "type": "string" } }, "required": ["accepted"], "additionalProperties": false } } } } } } }, "/v1/contact-channels/{channel_id}/verify": { "post": { "operationId": "contactChannelVerify", "summary": "Manually verify a contact channel", "tags": ["contacts"], "description": "Guardian-only manual attestation: marks the channel active/verified in the gateway store (source of truth) with a best-effort assistant mirror. Idempotent.", "parameters": [ { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The contact-channel id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "channel": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "type": "string" }, "type": { "type": "string" }, "address": { "type": "string" }, "isPrimary": { "type": "boolean" }, "externalChatId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "status": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "policy": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "verifiedAt": { "anyOf": [{ "type": "number" }, { "type": "null" }] }, "verifiedVia": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "inviteId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "revokedReason": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "blockedReason": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "lastSeenAt": { "anyOf": [{ "type": "number" }, { "type": "null" }] }, "interactionCount": { "type": "number" }, "lastInteraction": { "anyOf": [{ "type": "number" }, { "type": "null" }] }, "createdAt": { "anyOf": [{ "type": "number" }, { "type": "null" }] }, "updatedAt": { "anyOf": [{ "type": "number" }, { "type": "null" }] } }, "required": [ "id", "contactId", "type", "address", "isPrimary", "externalChatId", "status", "policy", "verifiedAt", "verifiedVia", "inviteId", "revokedReason", "blockedReason", "lastSeenAt", "interactionCount", "lastInteraction", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": ["ok", "channel"], "additionalProperties": false } } } } } } }, "/v1/credential-requests/peek": { "post": { "operationId": "credential_requests_peek", "summary": "Validate a credential-request token without consuming it", "tags": ["credential-requests"], "description": "Returns the service/field/label the link collects. The token travels in the body so it never appears in URLs or access logs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20 } }, "required": ["token"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "service": { "type": "string" }, "field": { "type": "string" }, "label": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "expiresAt": { "type": "number" } }, "required": ["service", "field", "label", "expiresAt"], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["INVALID", "EXPIRED", "USED"] }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false } ] } } } } } } }, "/v1/credential-requests/submit": { "post": { "operationId": "credential_requests_submit", "summary": "Consume a credential-request token and store the value", "tags": ["credential-requests"], "description": "Single-use: atomically claims the link, forwards the value to the assistant's credential store, and marks the link redeemed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20 }, "value": { "type": "string", "minLength": 1, "maxLength": 32768 } }, "required": ["token", "value"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["INVALID", "EXPIRED", "USED"] }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false } ] } } } } } } }, "/v1/feature-flags": { "get": { "operationId": "featureFlagsGet", "summary": "List all feature flags", "tags": ["feature-flags"], "description": "Returns all feature flags with their current values.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "flags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, "defaultEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, "description": { "type": "string" } }, "required": [ "key", "label", "enabled", "defaultEnabled", "description" ], "additionalProperties": false } } }, "required": ["flags"], "additionalProperties": false } } } } } } }, "/v1/feature-flags/{flag_key}": { "patch": { "operationId": "featureFlagsPatch", "summary": "Update a feature flag", "tags": ["feature-flags"], "description": "Set the enabled state of a single feature flag.", "parameters": [ { "name": "flag_key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The kebab-case flag identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "anyOf": [{ "type": "boolean" }, { "type": "string" }] } }, "required": ["enabled"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "enabled": { "anyOf": [{ "type": "boolean" }, { "type": "string" }] } }, "required": ["key", "enabled"], "additionalProperties": false } } } } } } }, "/v1/trust-rules": { "get": { "operationId": "trustRulesList", "summary": "List trust rules", "tags": ["trust-rules"], "description": "Returns trust rules, filtered to user-relevant rules by default. Pass include_all=true for the full set or origin/tool to filter.", "parameters": [ { "name": "origin", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by origin (default | user_defined)" }, { "name": "tool", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by tool name" }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "string" }, "description": "\"true\" to include soft-deleted rules" }, { "name": "include_all", "in": "query", "required": false, "schema": { "type": "string" }, "description": "\"true\" to disable the user-relevant filter" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tool": { "type": "string" }, "pattern": { "type": "string" }, "risk": { "type": "string", "enum": ["low", "medium", "high"] }, "description": { "type": "string" }, "origin": { "type": "string", "enum": ["default", "user_defined"] }, "userModified": { "type": "boolean" }, "deleted": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "tool", "pattern", "risk", "description", "origin", "userModified", "deleted", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": ["rules"], "additionalProperties": false } } } } } }, "post": { "operationId": "trustRuleCreate", "summary": "Create a trust rule", "tags": ["trust-rules"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string", "minLength": 1 }, "pattern": { "type": "string", "minLength": 1 }, "risk": { "type": "string", "enum": ["low", "medium", "high"] }, "description": { "type": "string", "minLength": 1 }, "scope": { "description": "Directory scope selected in the rule editor. Accepted on the wire but not yet persisted by the gateway.", "type": "string" } }, "required": ["tool", "pattern", "risk", "description"] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "type": "object", "properties": { "id": { "type": "string" }, "tool": { "type": "string" }, "pattern": { "type": "string" }, "risk": { "type": "string", "enum": ["low", "medium", "high"] }, "description": { "type": "string" }, "origin": { "type": "string", "enum": ["default", "user_defined"] }, "userModified": { "type": "boolean" }, "deleted": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "tool", "pattern", "risk", "description", "origin", "userModified", "deleted", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": ["rule"], "additionalProperties": false } } } } } } }, "/v1/trust-rules/suggest": { "post": { "operationId": "trustRuleSuggest", "summary": "Generate a trust-rule suggestion", "tags": ["trust-rules"], "description": "LLM-backed suggestion for a rule matching the given tool invocation. Returns 503 when the daemon suggestion relay is unavailable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string", "minLength": 1 }, "command": { "type": "string", "minLength": 1 }, "riskAssessment": { "type": "object", "properties": { "risk": { "type": "string" }, "reasoning": { "type": "string" }, "reasonDescription": { "type": "string" } }, "required": ["risk", "reasoning", "reasonDescription"] }, "scopeOptions": { "type": "array", "items": { "type": "object", "properties": { "pattern": { "type": "string" }, "label": { "type": "string" } }, "required": ["pattern", "label"] } }, "directoryScopeOptions": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "label": { "type": "string" } }, "required": ["scope", "label"] } }, "intent": { "type": "string", "enum": ["auto_approve", "escalate"] }, "existingRule": { "type": "object", "properties": { "id": { "type": "string" }, "pattern": { "type": "string" }, "risk": { "type": "string" } }, "required": ["id", "pattern", "risk"] } }, "required": [ "tool", "command", "riskAssessment", "scopeOptions", "intent" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestion": { "type": "object", "properties": { "pattern": { "type": "string" }, "risk": { "type": "string" }, "scope": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "description": { "type": "string" }, "scopeOptions": { "type": "array", "items": { "type": "object", "properties": { "pattern": { "type": "string" }, "label": { "type": "string" } }, "required": ["pattern", "label"], "additionalProperties": false } }, "directoryScopeOptions": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "label": { "type": "string" } }, "required": ["scope", "label"], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "pattern", "risk", "scope", "description", "scopeOptions" ], "additionalProperties": false } }, "required": ["suggestion"], "additionalProperties": false } } } } } } }, "/v1/trust-rules/{rule_id}": { "patch": { "operationId": "trustRuleUpdate", "summary": "Update a trust rule", "tags": ["trust-rules"], "description": "Updates risk and/or description. Updating a default-origin rule marks it userModified.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The trust rule id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "risk": { "type": "string", "enum": ["low", "medium", "high"] }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "type": "object", "properties": { "id": { "type": "string" }, "tool": { "type": "string" }, "pattern": { "type": "string" }, "risk": { "type": "string", "enum": ["low", "medium", "high"] }, "description": { "type": "string" }, "origin": { "type": "string", "enum": ["default", "user_defined"] }, "userModified": { "type": "boolean" }, "deleted": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "tool", "pattern", "risk", "description", "origin", "userModified", "deleted", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": ["rule"], "additionalProperties": false } } } } } }, "delete": { "operationId": "trustRuleDelete", "summary": "Delete a trust rule", "tags": ["trust-rules"], "description": "Soft-deletes the rule. Default-origin rules can be reset later.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The trust rule id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false } } } } } } }, "/v1/trust-rules/{rule_id}/reset": { "post": { "operationId": "trustRuleReset", "summary": "Reset a default trust rule", "tags": ["trust-rules"], "description": "Restores a default-origin rule to its registry risk and description, clearing userModified and deleted.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The trust rule id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "type": "object", "properties": { "id": { "type": "string" }, "tool": { "type": "string" }, "pattern": { "type": "string" }, "risk": { "type": "string", "enum": ["low", "medium", "high"] }, "description": { "type": "string" }, "origin": { "type": "string", "enum": ["default", "user_defined"] }, "userModified": { "type": "boolean" }, "deleted": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "tool", "pattern", "risk", "description", "origin", "userModified", "deleted", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": ["rule"], "additionalProperties": false } } } } } } } } }