{ "openapi": "3.1.0", "info": { "title": "Firefly Agent Bridge API", "version": "0.2.8", "description": "OpenAI-compatible Chat Completions and unified /v1/bridge orchestration extensions. Copyright 2026 Firefly Software Foundation. Author @ancongui.", "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" } }, "servers": [{ "url": "http://127.0.0.1:8766" }], "security": [{ "bearerAuth": [] }], "paths": { "/v1/bridge/status": { "get": { "operationId": "get_v1_bridge_status", "summary": "GET /v1/bridge/status", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/jobs": { "get": { "operationId": "get_v1_bridge_jobs", "summary": "GET /v1/bridge/jobs", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/jobs/{id}": { "get": { "operationId": "get_v1_bridge_jobs_id", "summary": "GET /v1/bridge/jobs/{id}", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/jobs/{id}/audit": { "get": { "operationId": "get_v1_bridge_jobs_id_audit", "summary": "GET /v1/bridge/jobs/{id}/audit", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "through", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Fix this to the first page's through value for an immutable export." }, { "name": "includePayloads", "in": "query", "schema": { "type": "string", "enum": ["true", "false"], "default": "false" }, "description": "Include complete tool inputs/results. Pages stop around 4 MB, always retaining at least one whole entry." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPage" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/jobs/{id}/tools": { "get": { "operationId": "get_v1_bridge_jobs_id_tools", "summary": "GET /v1/bridge/jobs/{id}/tools", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "filesOnly", "in": "query", "schema": { "type": "string", "enum": ["true", "false"], "default": "false" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolPage" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/jobs/{id}/tools/{tool}": { "get": { "operationId": "get_v1_bridge_jobs_id_tools_tool", "summary": "GET /v1/bridge/jobs/{id}/tools/{tool}", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tool", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolObservation" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/jobs/{id}/attempts": { "get": { "operationId": "get_v1_bridge_jobs_id_attempts", "summary": "GET /v1/bridge/jobs/{id}/attempts", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/jobs/{id}/pause": { "post": { "operationId": "post_v1_bridge_jobs_id_pause", "summary": "POST /v1/bridge/jobs/{id}/pause", "description": "Requires control authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "control", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/jobs/{id}/resume": { "post": { "operationId": "post_v1_bridge_jobs_id_resume", "summary": "POST /v1/bridge/jobs/{id}/resume", "description": "Requires control authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "control", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/jobs/{id}/result": { "get": { "operationId": "get_v1_bridge_jobs_id_result", "summary": "GET /v1/bridge/jobs/{id}/result", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Job is not terminal yet.", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/jobs/{id}/messages": { "get": { "operationId": "get_v1_bridge_jobs_id_messages", "summary": "GET /v1/bridge/jobs/{id}/messages", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_v1_bridge_jobs_id_messages", "summary": "POST /v1/bridge/jobs/{id}/messages", "description": "Requires submit authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "submit", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "202": { "description": "Accepted for asynchronous execution", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": ["text"], "additionalProperties": false } } } } } }, "/v1/bridge/jobs/{id}/cancel": { "post": { "operationId": "post_v1_bridge_jobs_id_cancel", "summary": "POST /v1/bridge/jobs/{id}/cancel", "description": "Requires control authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "control", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/jobs/{id}/retry": { "post": { "operationId": "post_v1_bridge_jobs_id_retry", "summary": "POST /v1/bridge/jobs/{id}/retry", "description": "Requires control authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Jobs"], "x-required-scope": "control", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Accepted for asynchronous execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/events": { "get": { "operationId": "get_v1_bridge_events", "summary": "GET /v1/bridge/events", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Events"], "x-required-scope": "read", "parameters": [ { "name": "Last-Event-ID", "in": "header", "schema": { "type": "integer", "minimum": 0 }, "description": "Resume after this event; expired cursors return 409." } ], "responses": { "200": { "description": "Successful response", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/workflow-runs": { "post": { "operationId": "post_v1_bridge_workflow-runs", "summary": "POST /v1/bridge/workflow-runs", "description": "Requires workflows authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Workflows"], "x-required-scope": "workflows", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "202": { "description": "Accepted for asynchronous execution", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": ["templateId", "inputs"], "additionalProperties": false } } } } }, "get": { "operationId": "get_v1_bridge_workflow-runs", "summary": "GET /v1/bridge/workflow-runs", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Workflows"], "x-required-scope": "read", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/workflow-runs/{id}": { "get": { "operationId": "get_v1_bridge_workflow-runs_id", "summary": "GET /v1/bridge/workflow-runs/{id}", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Workflows"], "x-required-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/workflow-runs/{id}/cancel": { "post": { "operationId": "post_v1_bridge_workflow-runs_id_cancel", "summary": "POST /v1/bridge/workflow-runs/{id}/cancel", "description": "Requires control authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Workflows"], "x-required-scope": "control", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/workflow-runs/{id}/pause": { "post": { "operationId": "post_v1_bridge_workflow-runs_id_pause", "summary": "POST /v1/bridge/workflow-runs/{id}/pause", "description": "Requires control authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Workflows"], "x-required-scope": "control", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/workflow-runs/{id}/resume": { "post": { "operationId": "post_v1_bridge_workflow-runs_id_resume", "summary": "POST /v1/bridge/workflow-runs/{id}/resume", "description": "Requires control authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Workflows"], "x-required-scope": "control", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/admin/pause": { "post": { "operationId": "post_v1_bridge_admin_pause", "summary": "POST /v1/bridge/admin/pause", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/admin/resume": { "post": { "operationId": "post_v1_bridge_admin_resume", "summary": "POST /v1/bridge/admin/resume", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/admin/stop": { "post": { "operationId": "post_v1_bridge_admin_stop", "summary": "POST /v1/bridge/admin/stop", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/v1/bridge/admin/tokens": { "get": { "operationId": "get_v1_bridge_admin_tokens", "summary": "GET /v1/bridge/admin/tokens", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_v1_bridge_admin_tokens", "summary": "POST /v1/bridge/admin/tokens", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "profiles": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "scopes": { "type": "array", "minItems": 1, "items": { "enum": ["read", "submit", "control", "workflows"] } } }, "required": ["id", "profiles", "scopes"], "additionalProperties": false } } } } } }, "/v1/bridge/admin/tokens/revoke": { "post": { "operationId": "post_v1_bridge_admin_tokens_revoke", "summary": "POST /v1/bridge/admin/tokens/revoke", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"], "additionalProperties": false } } } } } }, "/v1/bridge/hosts/heartbeat": { "post": { "operationId": "post_v1_bridge_hosts_heartbeat", "summary": "POST /v1/bridge/hosts/heartbeat", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"], "additionalProperties": false } } } } } }, "/v1/bridge/hosts/disconnect": { "post": { "operationId": "post_v1_bridge_hosts_disconnect", "summary": "POST /v1/bridge/hosts/disconnect", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"], "additionalProperties": false } } } } } }, "/v1/bridge/channel/pending": { "get": { "operationId": "get_v1_bridge_channel_pending", "summary": "GET /v1/bridge/channel/pending", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/channel/claim": { "post": { "operationId": "post_v1_bridge_channel_claim", "summary": "POST /v1/bridge/channel/claim", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostId": { "type": "string" }, "jobId": { "type": "string", "format": "uuid" } }, "required": ["hostId", "jobId"], "additionalProperties": false } } } } } }, "/v1/bridge/admin/templates": { "get": { "operationId": "get_v1_bridge_admin_templates", "summary": "GET /v1/bridge/admin/templates", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/admin/templates/{templateId}": { "put": { "operationId": "put_v1_bridge_admin_templates_templateId", "summary": "PUT /v1/bridge/admin/templates/{templateId}", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } } }, "delete": { "operationId": "delete_v1_bridge_admin_templates_templateId", "summary": "DELETE /v1/bridge/admin/templates/{templateId}", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bridge/channel/progress": { "post": { "operationId": "post_v1_bridge_channel_progress", "summary": "POST /v1/bridge/channel/progress", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostId": { "type": "string" }, "attemptId": { "type": "string", "format": "uuid" }, "fence": { "type": "string", "format": "uuid" }, "text": { "type": "string", "maxLength": 16000 } }, "required": ["hostId", "attemptId", "fence", "text"], "additionalProperties": false } } } } } }, "/v1/bridge/channel/complete": { "post": { "operationId": "post_v1_bridge_channel_complete", "summary": "POST /v1/bridge/channel/complete", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostId": { "type": "string" }, "attemptId": { "type": "string", "format": "uuid" }, "fence": { "type": "string", "format": "uuid" }, "result": { "type": "string", "maxLength": 100000 } }, "required": ["hostId", "attemptId", "fence", "result"], "additionalProperties": false } } } } } }, "/v1/bridge/channel/stopped": { "post": { "operationId": "post_v1_bridge_channel_stopped", "summary": "POST /v1/bridge/channel/stopped", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostId": { "type": "string" }, "attemptId": { "type": "string", "format": "uuid" }, "fence": { "type": "string", "format": "uuid" } }, "required": ["hostId", "attemptId", "fence"], "additionalProperties": false } } } } } }, "/v1/models": { "get": { "operationId": "get_v1_models", "summary": "GET /v1/models", "description": "Requires read authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["OpenAI compatibility"], "x-required-scope": "read", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Models" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/chat/completions": { "post": { "operationId": "post_v1_chat_completions", "summary": "POST /v1/chat/completions", "description": "Requires read + submit authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["OpenAI compatibility"], "x-required-scope": "read + submit", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 } }, { "name": "X-Bridge-Image-Revision", "in": "header", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Optional for image input: requires current verified configuration at first admission; included in the idempotency fingerprint. Text requests are unchanged." } ], "responses": { "200": { "description": "Validated completion JSON or buffered OpenAI SSE. Keepalive comments precede the final chunks; data: [DONE] ends the stream.", "headers": { "X-Bridge-Job-Id": { "description": "Durable job ID for console and recovery", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "202": { "description": "bridge.background=true: durable job receipt", "headers": { "X-Bridge-Job-Id": { "description": "Durable job ID for console and recovery", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "429": { "description": "Admission bound or subscription limit. A paused admitted job is retained.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until a known provider reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } } } }, "/v1/bridge/image-input/probes": { "post": { "operationId": "post_v1_bridge_image-input_probes", "summary": "POST /v1/bridge/image-input/probes", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [], "responses": { "202": { "description": "Accepted for asynchronous execution", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "required": ["profile", "request_id"], "additionalProperties": false } } } } } }, "/v1/bridge/image-input/probes/{id}": { "get": { "operationId": "get_v1_bridge_image-input_probes_id", "summary": "GET /v1/bridge/image-input/probes/{id}", "description": "Requires owner authorization. See api.md for lifecycle semantics, errors, and response fields.", "tags": ["Administration"], "x-required-scope": "owner", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Rejected request; error.code identifies the reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ffb_ token" } }, "schemas": { "ChatRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "model": { "type": "string", "pattern": "^bridge\\/[a-zA-Z0-9_-]{1,64}$" }, "messages": { "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": ["system", "developer", "user", "assistant", "tool"] }, "content": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "required": ["type", "text"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image_url" }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "const": "auto" } }, "required": ["url"], "additionalProperties": false } }, "required": ["type", "image_url"], "additionalProperties": false } ] } } ] }, { "type": "null" } ] }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "tool_calls": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "arguments": { "type": "string" } }, "required": ["name", "arguments"], "additionalProperties": false } }, "required": ["id", "type", "function"], "additionalProperties": false } }, "tool_call_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": ["role"], "additionalProperties": false } }, "tools": { "default": [], "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "description": { "type": "string", "maxLength": 10000 }, "parameters": { "default": { "type": "object", "properties": {} }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "strict": { "type": "boolean" } }, "required": ["name"], "additionalProperties": false } }, "required": ["type", "function"], "additionalProperties": false } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": ["none", "auto", "required"] }, { "type": "object", "properties": { "type": { "type": "string", "const": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" } }, "required": ["name"], "additionalProperties": false } }, "required": ["type", "function"], "additionalProperties": false } ] }, "parallel_tool_calls": { "default": true, "type": "boolean" }, "response_format": { "default": { "type": "text" }, "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "json_object" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "json_schema" }, "json_schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "description": { "type": "string" }, "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "strict": { "type": "boolean" } }, "required": ["name", "schema"], "additionalProperties": false } }, "required": ["type", "json_schema"], "additionalProperties": false } ] }, "stream": { "default": false, "type": "boolean" }, "stream_options": { "anyOf": [ { "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, { "type": "null" } ] }, "n": { "default": 1, "type": "number", "const": 1 }, "bridge": { "default": {}, "type": "object", "properties": { "execution": { "default": "inference", "type": "string", "enum": ["inference", "agent", "channel"] }, "background": { "default": false, "type": "boolean" } }, "additionalProperties": false } }, "required": ["model", "messages"], "additionalProperties": false }, "ChatCompletion": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "const": "assistant" }, "content": { "type": ["string", "null"] }, "tool_calls": { "type": "array", "items": { "type": "object" } } } }, "finish_reason": { "enum": ["stop", "tool_calls"] } }, "required": ["index", "message", "finish_reason"], "additionalProperties": false } }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": ["id", "object", "created", "model", "choices"], "additionalProperties": false }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "required": ["prompt_tokens", "completion_tokens", "total_tokens"], "additionalProperties": false }, "Models": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "model" }, "created": { "type": "integer" }, "owned_by": { "type": "string" }, "worker": { "enum": ["codex", "claude"] }, "native_model": { "type": ["string", "null"] }, "image_input": { "type": "object", "properties": { "status": { "enum": ["unverified", "verified", "unsupported"] }, "config_revision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "mime_types": { "type": "array", "items": { "type": "string" } }, "max_images": { "const": 5 }, "max_decoded_bytes": { "const": 6000000 }, "detail": { "const": "auto" }, "verified_at": { "type": "string" }, "probe_job_id": { "type": "string", "format": "uuid" } }, "required": [ "status", "config_revision", "mime_types", "max_images", "max_decoded_bytes", "detail" ], "additionalProperties": false } }, "required": [ "id", "object", "created", "owned_by", "worker", "native_model", "image_input" ], "additionalProperties": false } } }, "required": ["object", "data"], "additionalProperties": false }, "Template": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "description": { "default": "", "type": "string", "maxLength": 2000 }, "inputs": { "default": [], "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" } }, "steps": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 100000 }, "profile": { "default": "default", "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" } }, "required": ["id", "prompt", "profile"], "additionalProperties": false } } }, "required": ["id", "description", "inputs", "steps"], "additionalProperties": false }, "Job": { "type": "object", "required": ["id", "prompt", "profile", "mode", "status", "messages"], "properties": { "id": { "type": "string", "format": "uuid" }, "prompt": { "type": "string" }, "profile": { "type": "string" }, "mode": { "enum": ["cli", "channel"] }, "status": { "enum": [ "queued", "running", "pause_requested", "paused", "cancel_requested", "succeeded", "failed", "canceled", "interrupted", "timed_out" ] }, "sessionId": { "type": "string", "format": "uuid" }, "result": { "type": "string" }, "completion": { "$ref": "#/components/schemas/ChatRequest" }, "usage": { "$ref": "#/components/schemas/Usage" }, "error": { "type": "string" }, "retryAt": { "type": "integer", "description": "Provider retry time in Unix milliseconds" }, "messages": { "type": "array", "items": { "type": "object" } }, "pendingMessages": { "type": "array", "items": { "type": "object" } }, "compactions": { "type": "integer" }, "subagents": { "type": "object" } } }, "ToolObservation": { "type": "object", "properties": { "id": { "type": "integer" }, "jobId": { "type": "string", "format": "uuid" }, "attemptId": { "type": "string", "format": "uuid" }, "toolId": { "type": "string" }, "name": { "type": "string" }, "sessionId": { "type": "string" }, "parentToolUseId": { "type": "string" }, "status": { "enum": ["requested", "succeeded", "failed", "unknown"] }, "requestedAt": { "type": "string" }, "completedAt": { "type": "string" }, "durationMs": { "type": "number" }, "file": { "type": "object", "properties": { "path": { "type": "string" }, "operation": { "enum": ["read", "write", "edit"] } }, "required": ["path", "operation"], "additionalProperties": false }, "input": {}, "output": {} }, "required": ["id", "jobId", "attemptId", "toolId", "status"], "additionalProperties": false }, "AuditEntry": { "type": "object", "properties": { "id": { "type": "integer" }, "jobId": { "type": "string", "format": "uuid" }, "attemptId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string" }, "type": { "type": "string" }, "source": { "enum": ["claude", "bridge", "client"] }, "createdAt": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "required": ["id", "jobId", "type", "source", "createdAt", "data"], "additionalProperties": false }, "AuditPage": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } }, "through": { "type": "integer" }, "nextCursor": { "type": ["integer", "null"] }, "summary": { "type": "object", "properties": { "tools": { "type": "integer" }, "files": { "type": "integer" }, "changedFiles": { "type": "integer" }, "failedTools": { "type": "integer" }, "unknownTools": { "type": "integer" }, "events": { "type": "integer" }, "coverage": { "enum": ["native_tools", "client_functions", "host_lifecycle"] } }, "required": [ "tools", "files", "changedFiles", "failedTools", "unknownTools", "events", "coverage" ], "additionalProperties": false } }, "required": ["entries", "through", "nextCursor", "summary"], "additionalProperties": false }, "ToolPage": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolObservation" } }, "nextCursor": { "type": ["integer", "null"] } }, "required": ["tools", "nextCursor"], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string" }, "param": { "type": "null" }, "requestId": { "type": "string" }, "job_id": { "type": "string", "format": "uuid" } }, "required": ["code", "message", "type", "param"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false } } } }