This repository has been archived on 2026-11-08. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
carl/docs/foundation/client-api.openapi.json

1956 lines
51 KiB
JSON

{
"openapi": "3.1.0",
"info": {
"title": "KofTwentyTwo family agent client API",
"version": "1.0.0",
"description": "Optional dedicated-audience JWT API. Private chats by default; immutable explicit shared participant scope. Under qualification; see CLIENT-API.md for exact supported JWT profile and release state."
},
"servers": [
{
"url": "https://{host}/api/agent/v1",
"variables": {
"host": {
"default": "carl.example"
}
}
}
],
"security": [
{
"AccessToken": []
}
],
"paths": {
"/me": {
"get": {
"operationId": "currentMember",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Me"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/members": {
"get": {
"operationId": "listMembers",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Members"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/conversations": {
"get": {
"operationId": "listConversations",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationList"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "after",
"in": "query",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0,
"default": 0
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 25
}
}
]
}
},
"/conversations/{conversationId}": {
"parameters": [
{
"name": "conversationId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"put": {
"operationId": "createConversation",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Conversation"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateConversation"
}
}
}
}
},
"get": {
"operationId": "getConversation",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Conversation"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/conversations/{conversationId}/turns": {
"parameters": [
{
"name": "conversationId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"get": {
"operationId": "listTurns",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TurnList"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "after",
"in": "query",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0,
"default": 0
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 25
}
}
]
}
},
"/conversations/{conversationId}/turns/{turnId}": {
"parameters": [
{
"name": "conversationId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "turnId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"put": {
"operationId": "submitTurn",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Turn"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitTurn"
}
}
}
}
},
"get": {
"operationId": "getTurn",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Turn"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/conversations/{conversationId}/turns/{turnId}/cancel": {
"parameters": [
{
"name": "conversationId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "turnId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"post": {
"operationId": "cancelTurn",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Turn"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/conversations/{conversationId}/workflows/{kind}/{requestId}": {
"parameters": [
{
"name": "conversationId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "kind",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^[a-z][a-z0-9.-]{0,63}$"
}
},
{
"name": "requestId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"put": {
"operationId": "startExplicitWorkflow",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowResult"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowInput"
}
}
}
}
},
"get": {
"operationId": "getWorkflow",
"responses": {
"200": {
"description": "Successful authenticated result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowResult"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid dedicated access token or membership",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Origin or author denied",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Absent or inaccessible resource",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Unsupported method",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Idempotency conflict or active conversation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body exceeds 64 KiB",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"421": {
"description": "Incorrect public Host",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Capacity or rate limit; honor Retry-After",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
},
"description": "Seconds before retry; preserve logical request ID."
}
}
},
"503": {
"description": "Unavailable or not ready",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"AccessToken": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "RS256 RFC 9068 JWT access token (typ at+jwt), scope agent:chat"
}
},
"schemas": {
"Error": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
}
},
"required": [
"code"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
},
"Me": {
"type": "object",
"properties": {
"memberId": {
"type": "string"
},
"householdId": {
"type": "string"
},
"privateTools": {
"type": "string",
"const": "explicit-read-only"
},
"sharedTools": {
"type": "string",
"const": "none"
},
"permissionRevision": {
"type": "string"
}
},
"required": [
"memberId",
"householdId",
"privateTools",
"sharedTools",
"permissionRevision"
],
"additionalProperties": false
},
"Members": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"items"
],
"additionalProperties": false
},
"Conversation": {
"type": "object",
"properties": {
"sequence": {
"type": "integer",
"format": "int64"
},
"id": {
"type": "string",
"format": "uuid"
},
"household": {
"type": "string"
},
"owner": {
"type": "string"
},
"shared": {
"type": "boolean"
},
"participants": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true,
"minItems": 1,
"maxItems": 16
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"sequence",
"id",
"household",
"owner",
"shared",
"participants",
"createdAt"
],
"additionalProperties": false
},
"Turn": {
"type": "object",
"properties": {
"sequence": {
"type": "integer",
"format": "int64"
},
"id": {
"type": "string",
"format": "uuid"
},
"conversationId": {
"type": "string",
"format": "uuid"
},
"author": {
"type": "string"
},
"message": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"RUNNING",
"CANCEL_REQUESTED",
"COMPLETED",
"UNKNOWN"
]
},
"reply": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"sequence",
"id",
"conversationId",
"author",
"message",
"status",
"reply",
"createdAt"
],
"additionalProperties": false
},
"CreateConversation": {
"type": "object",
"properties": {
"shared": {
"type": "boolean",
"default": false
},
"participants": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true,
"minItems": 1,
"maxItems": 16
}
},
"required": [],
"additionalProperties": false
},
"SubmitTurn": {
"type": "object",
"properties": {
"message": {
"type": "string",
"minLength": 1
}
},
"required": [
"message"
],
"additionalProperties": false
},
"WorkflowInput": {
"type": "object",
"properties": {
"input": {
"type": "object",
"description": "Consumer-owned narrow typed input; no authoritative identity or audience fields."
}
},
"required": [
"input"
],
"additionalProperties": false
},
"WorkflowResult": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"PENDING",
"COMPLETE",
"PARTIAL",
"FAILED",
"UNKNOWN"
]
},
"artifactId": {
"type": [
"string",
"null"
]
},
"summary": {
"type": [
"string",
"null"
]
},
"artifact": {}
},
"required": [
"status",
"artifactId",
"summary",
"artifact"
],
"additionalProperties": false
},
"ConversationList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Conversation"
}
}
},
"required": [
"items"
],
"additionalProperties": false
},
"TurnList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Turn"
}
}
},
"required": [
"items"
],
"additionalProperties": false
}
}
}
}