{ "openapi": "3.1.0", "info": { "title": "TokST REST API", "version": "0.8.3", "description": "Authenticated memory, workspace, Agent, and session APIs for TokST. Memory content accepts Markdown." }, "servers": [ { "url": "https://api.tokst.com", "description": "TokST Cloud API" } ], "tags": [ { "name": "Memories", "description": "Durable Markdown memories and retrieval." }, { "name": "Workspaces", "description": "Workspace membership and shared context." }, { "name": "Sessions", "description": "Agent session lifecycle and candidate governance." }, { "name": "Automatic Memory", "description": "ACP automatic-memory policy and privacy metadata." }, { "name": "Agents", "description": "Trusted Agent identities and handoffs." } ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "mcp" ] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "TokST API key or OAuth access token" }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.tokst.com/oauth/authorize", "tokenUrl": "https://api.tokst.com/oauth/token", "scopes": { "mcp": "Use the TokST MCP tool surface." } } } } }, "schemas": { "Memory": { "type": "object", "required": [ "id", "workspaceId", "atlasId", "content" ], "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown memory content." }, "type": { "type": "string", "enum": [ "fact", "decision", "preference", "task", "architecture", "note" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "archived" ] } } }, "Error": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } }, "Identifier": { "type": "string", "description": "TokST resource identifier." } } }, "paths": { "/health": { "get": { "operationId": "healthCheck", "summary": "Check TokST API health", "security": [], "responses": { "200": { "description": "Service is available.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/status": { "get": { "operationId": "getAccountStatus", "tags": [ "Workspaces" ], "summary": "Get account quotas and accessible workspace counts", "responses": { "200": { "description": "Account status returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "plan": { "type": "string" }, "usage": { "type": "object", "additionalProperties": true, "properties": {} }, "workspaces": { "type": "object", "additionalProperties": true, "properties": {} } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/memories": { "get": { "operationId": "listMemories", "tags": [ "Memories" ], "summary": "List accessible memories", "parameters": [ { "name": "atlas_id", "in": "query", "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Accessible memories returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "memories" ], "properties": { "memories": { "type": "array", "items": { "type": "object", "required": [ "id", "workspaceId", "atlasId", "content" ], "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown memory content." }, "type": { "type": "string", "enum": [ "fact", "decision", "preference", "task", "architecture", "note" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "archived" ] } } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } }, "post": { "operationId": "createMemory", "tags": [ "Memories" ], "summary": "Create a Markdown memory", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "title": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string", "enum": [ "fact", "decision", "preference", "task", "architecture", "note" ] }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Memory created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "memory": { "type": "object", "required": [ "id", "workspaceId", "atlasId", "content" ], "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown memory content." }, "type": { "type": "string", "enum": [ "fact", "decision", "preference", "task", "architecture", "note" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "archived" ] } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/memories/search": { "post": { "operationId": "searchMemories", "tags": [ "Memories" ], "summary": "Search memories with keyword, semantic, or hybrid retrieval", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "atlas_id": { "type": "string", "description": "TokST resource identifier." }, "workspace_id": { "type": "string", "description": "TokST resource identifier." }, "mode": { "type": "string", "enum": [ "auto", "keyword", "semantic", "hybrid" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } } } } }, "responses": { "200": { "description": "Search results returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "memories" ], "properties": { "memories": { "type": "array", "items": { "type": "object", "required": [ "id", "workspaceId", "atlasId", "content" ], "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown memory content." }, "type": { "type": "string", "enum": [ "fact", "decision", "preference", "task", "architecture", "note" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "archived" ] } } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/memories/{memoryId}": { "get": { "operationId": "getMemory", "tags": [ "Memories" ], "summary": "Get one memory", "parameters": [ { "name": "memoryId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Memory returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "workspaceId", "atlasId", "content" ], "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown memory content." }, "type": { "type": "string", "enum": [ "fact", "decision", "preference", "task", "architecture", "note" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "archived" ] } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } }, "patch": { "operationId": "updateMemory", "tags": [ "Memories" ], "summary": "Update memory Markdown or metadata", "parameters": [ { "name": "memoryId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Memory updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "workspaceId", "atlasId", "content" ], "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown memory content." }, "type": { "type": "string", "enum": [ "fact", "decision", "preference", "task", "architecture", "note" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "archived" ] } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } }, "delete": { "operationId": "deleteMemory", "tags": [ "Memories" ], "summary": "Delete a memory", "parameters": [ { "name": "memoryId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Memory deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/atlases": { "get": { "operationId": "listAtlases", "tags": [ "Workspaces" ], "summary": "List accessible Atlases", "responses": { "200": { "description": "Accessible Atlases returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "atlases" ], "properties": { "atlases": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } }, "post": { "operationId": "createAtlas", "tags": [ "Workspaces" ], "summary": "Create an Atlas", "responses": { "201": { "description": "Atlas created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "atlas": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "name": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/workspaces": { "get": { "operationId": "listWorkspaces", "tags": [ "Workspaces" ], "summary": "List accessible workspaces", "responses": { "200": { "description": "Accessible workspaces returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspaces" ], "properties": { "workspaces": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "personal", "team" ] } } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } }, "post": { "operationId": "createWorkspace", "tags": [ "Workspaces" ], "summary": "Create a personal or team workspace", "responses": { "201": { "description": "Workspace created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "workspace": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "name": { "type": "string" }, "type": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/agents": { "get": { "operationId": "listAgents", "tags": [ "Agents" ], "summary": "List trusted Agents in a workspace", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Trusted Agents returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "displayName": { "type": "string" }, "status": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/agent-messages": { "post": { "operationId": "sendAgentMessage", "tags": [ "Agents" ], "summary": "Send an Agent handoff, question, update, or decision", "responses": { "201": { "description": "Agent message created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "message": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "content": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/auto": { "get": { "operationId": "getAutomaticMemory", "tags": [ "Automatic Memory" ], "summary": "Read automatic-memory policy for a user, workspace, or Atlas", "parameters": [ { "name": "workspaceId", "in": "query", "schema": { "type": "string", "description": "TokST resource identifier." } }, { "name": "atlasId", "in": "query", "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Automatic-memory policy returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean" }, "paused": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "acp" ] } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } }, "put": { "operationId": "configureAutomaticMemory", "tags": [ "Automatic Memory" ], "summary": "Enable, pause, or route ACP automatic memory", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "properties": { "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "enabled": { "type": "boolean" }, "paused": { "type": "boolean" }, "autoCompileCandidates": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Automatic-memory policy updated.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "enabled": { "type": "boolean" }, "paused": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "acp" ] } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/auto/redaction-audits": { "post": { "operationId": "recordAutomaticMemoryRedactionAudit", "tags": [ "Automatic Memory" ], "summary": "Record local redaction metadata without sending raw session content", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruleCount", "blocked" ], "properties": { "sessionId": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "ruleCount": { "type": "integer", "minimum": 0, "maximum": 100 }, "blocked": { "type": "boolean" }, "reason": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "201": { "description": "Redaction audit recorded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions": { "get": { "operationId": "listSessions", "tags": [ "Sessions" ], "summary": "List Sessions visible to the caller", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } }, { "name": "archived", "in": "query", "schema": { "type": "string", "enum": [ "active", "only", "all" ] } }, { "name": "diagnostics", "in": "query", "schema": { "type": "string", "enum": [ "exclude", "only", "all" ] } }, { "name": "activityState", "in": "query", "schema": { "type": "string", "enum": [ "capturing", "idle", "closing", "attention", "needs_attention" ] } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "manual", "workbuddy", "opencode", "pi", "codex", "claude", "claude-desktop", "acp", "diagnostic" ] } }, { "name": "automaticMemory", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Sessions and workspace Session statistics returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "sessions": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "status": { "type": "string" }, "activityState": { "type": "string", "enum": [ "capturing", "idle", "closing", "attention", "completed", "archived" ] }, "closeAt": { "type": "string", "format": "date-time" }, "archiveAt": { "type": "string", "format": "date-time" }, "closeReason": { "type": "string" }, "captureMode": { "type": "string", "enum": [ "assisted", "acp" ] }, "compilationStatus": { "type": "string" } } } }, "stats": { "type": "object", "additionalProperties": true, "properties": { "capturing": { "type": "integer" }, "idle": { "type": "integer" }, "closing": { "type": "integer" }, "attention": { "type": "integer" }, "completed": { "type": "integer" }, "archived": { "type": "integer" }, "needsAttention": { "type": "integer" }, "automaticMemory": { "type": "integer" }, "pendingCandidates": { "type": "integer" } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } }, "post": { "operationId": "startSession", "tags": [ "Sessions" ], "summary": "Start a durable Agent Session, including an ACP automatic-memory Session", "responses": { "201": { "description": "Session started.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "session": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "status": { "type": "string" }, "acpSessionId": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/{sessionId}": { "delete": { "operationId": "deleteSession", "tags": [ "Sessions" ], "summary": "Delete a Session and its captured Session records while retaining any formal memory", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Session deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "deletedId": { "type": "string", "description": "TokST resource identifier." }, "automaticMemoryId": { "type": "string", "description": "TokST resource identifier." } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/bulk": { "post": { "operationId": "bulkManageSessions", "tags": [ "Sessions" ], "summary": "Archive, restore, or delete up to 100 visible Sessions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionIds", "action" ], "properties": { "sessionIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "description": "TokST resource identifier." } }, "action": { "type": "string", "enum": [ "archive", "restore", "delete" ] }, "reason": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Each Session is processed under the caller's workspace permission.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "action": { "type": "string" }, "requested": { "type": "integer" }, "processedIds": { "type": "array", "items": { "type": "string", "description": "TokST resource identifier." } }, "failures": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/{sessionId}/events": { "post": { "operationId": "recordSessionEvent", "tags": [ "Sessions" ], "summary": "Record a sanitized Session event and its preserved result from a local automatic-memory bridge", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sourceEventId", "eventType" ], "properties": { "sourceEventId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "session_started", "user_message", "assistant_message", "tool_started", "tool_completed", "file_changed", "command_completed", "checkpoint_hint", "session_ended", "turn_started", "assistant_final", "heartbeat", "session_failed" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "summary": { "type": "string" }, "content": { "type": "string", "maxLength": 180000, "description": "Sanitized event content. Final Agent replies and meaningful result tables are retained as Session evidence." }, "contentHash": { "type": "string" }, "captureMode": { "type": "string", "enum": [ "acp" ] }, "relayVersion": { "type": "string" }, "adapter": { "type": "string", "enum": [ "acp", "workbuddy", "opencode", "pi", "codex", "claude", "claude-desktop" ] }, "adapterVersion": { "type": "string" }, "nativeSessionId": { "type": "string" }, "projectPathHash": { "type": "string" }, "toolResultSummary": { "type": "string" }, "acpEventId": { "type": "string" }, "acpMessageId": { "type": "string" } } } } } }, "responses": { "201": { "description": "Session event recorded.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "receipt": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "status": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/{sessionId}/finalize": { "post": { "operationId": "finalizeSession", "tags": [ "Sessions" ], "summary": "Finalize a Session and compile approved candidates", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Session finalized.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "session": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "status": { "type": "string" } } }, "memories": { "type": "array", "items": { "type": "object", "required": [ "id", "workspaceId", "atlasId", "content" ], "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "workspaceId": { "type": "string", "description": "TokST resource identifier." }, "atlasId": { "type": "string", "description": "TokST resource identifier." }, "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown memory content." }, "type": { "type": "string", "enum": [ "fact", "decision", "preference", "task", "architecture", "note" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "archived" ] } } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/{sessionId}/units": { "post": { "operationId": "createOrResumeSessionMemoryUnit", "tags": [ "Sessions" ], "summary": "Create or resume one durable task within a native Agent Session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "task", "semanticKey" ], "properties": { "task": { "type": "string", "maxLength": 2000 }, "semanticKey": { "type": "string", "maxLength": 128 }, "startedEventId": { "type": "string" } } } } } }, "responses": { "201": { "description": "Task memory unit created or resumed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "unit": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "task": { "type": "string" }, "semanticKey": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/{sessionId}/units/{unitId}/finalize": { "post": { "operationId": "finalizeSessionMemoryUnit", "tags": [ "Sessions" ], "summary": "Compile one task unit into its linked formal memory while the Session remains active", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } }, { "name": "unitId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "maxLength": 60000 }, "compileCandidates": { "type": "boolean" }, "sourceEventIds": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "endedEventId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Task unit saved to formal memory.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "session": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." } } }, "units": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "memoryId": { "type": "string", "description": "TokST resource identifier." } } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/{sessionId}/complete": { "post": { "operationId": "completeAutomaticSession", "tags": [ "Sessions" ], "summary": "Close an automatic Session after its final task unit has been stored", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Session completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "session": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "status": { "type": "string", "enum": [ "completed" ] } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/{sessionId}/reopen": { "post": { "operationId": "reopenAcpSession", "tags": [ "Sessions" ], "summary": "Resume an ACP Session and retain its automatic memory identity", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "ACP Session resumed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "session": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "status": { "type": "string" }, "automaticMemoryId": { "type": "string", "description": "TokST resource identifier." }, "compilationStatus": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/v1/sessions/{sessionId}/automatic-memory/revert": { "post": { "operationId": "revertAutomaticMemory", "tags": [ "Sessions" ], "summary": "Archive the automatic memory linked to an ACP Session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "TokST resource identifier." } } ], "responses": { "200": { "description": "Automatic memory archived and Session audit retained.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "session": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "TokST resource identifier." }, "automaticMemoryId": { "type": "string", "description": "TokST resource identifier." }, "compilationStatus": { "type": "string", "enum": [ "reverted" ] } } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } }, "/mcp": { "post": { "operationId": "tokstMcp", "tags": [ "Agents" ], "summary": "TokST Streamable HTTP MCP endpoint", "description": "Connect MCP clients with OAuth or a TokST API key.", "responses": { "200": { "description": "MCP JSON-RPC response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "jsonrpc": { "type": "string" }, "result": { "type": "object", "additionalProperties": true, "properties": {} }, "error": { "type": "object", "additionalProperties": true, "properties": {} } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "403": { "description": "The credential or workspace role does not permit this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "404": { "description": "The requested route or accessible resource was not found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "409": { "description": "The resource state prevents this action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "429": { "description": "Monthly quota or rolling rate limit reached. Read RateLimit and Retry-After headers before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds before the next permitted request." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string", "description": "Legacy stable error code alias." }, "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable recovery message." }, "requestId": { "type": "string", "description": "Optional request identifier for support." } } } } } } } } } } }