{ "openapi": "3.1.0", "info": { "title": "AgentMembers Public API", "version": "1.0.0", "description": "REST API pública do AgentMembers, autenticada por API keys escopadas por empresa.\n\n**Autenticação:** envie `Authorization: Bearer am_live_...` em todas as requisições. Crie e gerencie suas chaves em `/admin/integracoes`.\n\n**Rate limit:** 60 requisições por minuto por chave. Resposta 429 inclui `retry_after_seconds`.\n\n**Paginação:** baseada em cursor — use `next_cursor` da resposta como `cursor` na próxima chamada.\n\n**MCP server:** o mesmo conjunto de operações está disponível como servidor MCP em `POST /api/public/mcp` para clientes compatíveis (Claude, Cursor, etc)." }, "servers": [ { "url": "https://agentmembers.com", "description": "Current host" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Agents", "description": "Listar, criar, editar e excluir agentes." }, { "name": "Conversations", "description": "Listar conversas e mensagens dos agentes." }, { "name": "Skills", "description": "Listar, criar, editar e excluir skills (plugin Skills)." }, { "name": "MCP", "description": "Model Context Protocol endpoint." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "am_live_", "description": "API key gerada em /admin/integracoes. Permissões herdam o role do criador (owner/admin para escrita)." } }, "schemas": { "Agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "format": "uri", "nullable": true }, "category": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "free", "locked", "hidden" ] }, "kind": { "type": "string", "enum": [ "chat", "external_link", "embed" ] }, "external_url": { "type": "string", "format": "uri", "nullable": true }, "is_active": { "type": "boolean" }, "allow_anonymous": { "type": "boolean", "description": "Anonymous visitors can chat via the public /e/... link." }, "lead_capture_enabled": { "type": "boolean" }, "lead_capture_fields": { "type": "array", "items": { "type": "string", "enum": [ "name", "email", "whatsapp" ] }, "minItems": 1, "description": "Fields requested in the lead capture form." }, "lead_capture_instructions": { "type": "string", "nullable": true }, "lead_webhook_url": { "type": "string", "format": "uri", "nullable": true }, "lead_webhook_custom_field_key": { "type": "string", "nullable": true }, "lead_webhook_custom_field_source": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AgentCreate": { "type": "object", "required": [ "name", "slug", "system_prompt" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 120 }, "system_prompt": { "type": "string" }, "description": { "type": "string" }, "avatar_url": { "type": "string", "format": "uri" }, "visibility": { "type": "string", "enum": [ "free", "locked", "hidden" ] }, "kind": { "type": "string", "enum": [ "chat", "external_link", "embed" ] }, "external_url": { "type": "string", "format": "uri" }, "embed_code": { "type": "string" }, "category": { "type": "string" }, "response_mode": { "type": "string", "enum": [ "faithful", "consultant", "creator" ] }, "is_active": { "type": "boolean" }, "allow_anonymous": { "type": "boolean" }, "lead_capture_enabled": { "type": "boolean" }, "lead_capture_fields": { "type": "array", "items": { "type": "string", "enum": [ "name", "email", "whatsapp" ] }, "minItems": 1, "description": "Fields requested in the lead capture form." }, "lead_capture_instructions": { "type": "string", "maxLength": 2000 }, "lead_webhook_url": { "type": "string", "format": "uri", "description": "HTTPS endpoint that receives POST payloads for each captured lead." }, "lead_webhook_secret": { "type": "string", "minLength": 8, "maxLength": 200, "description": "HMAC-SHA256 secret used to sign webhook payloads. Never returned by the API." }, "lead_webhook_custom_field_key": { "type": "string", "maxLength": 120 }, "lead_webhook_custom_field_source": { "type": "string", "maxLength": 120 } } }, "AgentPatch": { "type": "object", "required": [], "properties": { "name": { "type": "string", "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 120 }, "system_prompt": { "type": "string" }, "description": { "type": "string" }, "avatar_url": { "type": "string", "format": "uri" }, "visibility": { "type": "string", "enum": [ "free", "locked", "hidden" ] }, "kind": { "type": "string", "enum": [ "chat", "external_link", "embed" ] }, "external_url": { "type": "string", "format": "uri" }, "embed_code": { "type": "string" }, "category": { "type": "string" }, "response_mode": { "type": "string", "enum": [ "faithful", "consultant", "creator" ] }, "is_active": { "type": "boolean" }, "allow_anonymous": { "type": "boolean" }, "lead_capture_enabled": { "type": "boolean" }, "lead_capture_fields": { "type": "array", "items": { "type": "string", "enum": [ "name", "email", "whatsapp" ] }, "minItems": 1, "description": "Fields requested in the lead capture form." }, "lead_capture_instructions": { "type": "string", "maxLength": 2000 }, "lead_webhook_url": { "type": "string", "format": "uri", "description": "HTTPS endpoint that receives POST payloads for each captured lead." }, "lead_webhook_secret": { "type": "string", "minLength": 8, "maxLength": 200, "description": "HMAC-SHA256 secret used to sign webhook payloads. Never returned by the API." }, "lead_webhook_custom_field_key": { "type": "string", "maxLength": 120 }, "lead_webhook_custom_field_source": { "type": "string", "maxLength": 120 } } }, "Conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string", "nullable": true }, "last_message_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object" }, "nullable": true }, "audio_url": { "type": "string", "format": "uri", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Skill": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "long_description_md": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "cover_url": { "type": "string", "format": "uri", "nullable": true }, "category_id": { "type": "string", "format": "uuid", "nullable": true }, "visibility": { "type": "string", "enum": [ "free", "locked", "hidden" ] }, "is_published": { "type": "boolean" }, "is_active": { "type": "boolean" }, "source_kind": { "type": "string", "enum": [ "hosted", "external" ] }, "external_url": { "type": "string", "format": "uri", "nullable": true }, "install_command": { "type": "string", "nullable": true }, "compat_claude": { "type": "boolean" }, "compat_codex": { "type": "boolean" }, "clicks_count": { "type": "integer" }, "downloads_count": { "type": "integer" }, "version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SkillCreate": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 120 }, "name": { "type": "string", "maxLength": 160 }, "description": { "type": "string", "maxLength": 500 }, "long_description_md": { "type": "string", "maxLength": 20000 }, "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "cover_url": { "type": "string", "format": "uri" }, "category_id": { "type": "string", "format": "uuid" }, "visibility": { "type": "string", "enum": [ "free", "locked", "hidden" ], "default": "free" }, "is_published": { "type": "boolean", "default": false }, "source_kind": { "type": "string", "enum": [ "hosted", "external" ], "default": "external" }, "external_url": { "type": "string", "format": "uri", "description": "Obrigatório quando source_kind=external." }, "install_command": { "type": "string", "maxLength": 300 }, "compat_claude": { "type": "boolean", "default": true }, "compat_codex": { "type": "boolean", "default": true }, "is_active": { "type": "boolean", "default": true }, "version": { "type": "string", "maxLength": 30 } } } } }, "paths": { "/api/public/v1/agents": { "get": { "tags": [ "Agents" ], "summary": "Listar agentes", "description": "Lista os agentes da empresa autenticada. Requer scope `agents:read`.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Maximum items to return (default 50, max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Pagination cursor — pass `next_cursor` from the previous response." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "next_cursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Agents" ], "summary": "Criar agente", "description": "Requer scope `agents:write` e key criada por owner/admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/agents/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Agents" ], "summary": "Obter agente", "description": "Requer scope `agents:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Agents" ], "summary": "Atualizar agente", "description": "Requer scope `agents:write` e role owner/admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPatch" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Agents" ], "summary": "Excluir agente", "description": "Requer scope `agents:write` e role owner/admin.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/conversations": { "get": { "tags": [ "Conversations" ], "summary": "Listar conversas", "description": "Lista conversas dos agentes da empresa. Requer scope `conversations:read`.", "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filtrar conversas por agente." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Maximum items to return (default 50, max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Pagination cursor — pass `next_cursor` from the previous response." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "next_cursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/conversations/{id}/messages": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Conversations" ], "summary": "Listar mensagens", "description": "Lista as mensagens de uma conversa em ordem cronológica. Requer scope `conversations:read`.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Cursor — retorna mensagens com `created_at` MAIOR que o cursor." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "next_cursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/agents/{id}/messages": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Agents" ], "summary": "Enviar mensagem ao agente (prediction)", "description": "Envia uma mensagem para o agente e recebe a resposta. Ideal para integrar o agente em canais externos (Telegram, WhatsApp, seu backend).\n\n**Sessão:** Na primeira chamada, omita `conversation_id` — a resposta trará o `conversation_id` recém-criado. Envie esse mesmo `conversation_id` nas próximas chamadas para continuar a mesma conversa.\n\nAlternativamente, use `session_id` (ex.: `chat_id` do Telegram) e o servidor reaproveita automaticamente a conversa da mesma sessão externa.\n\n**Streaming:** envie `stream: true` no body OU `Accept: text/event-stream` para receber SSE (`meta`/`token`/`done`/`error`).\n\nRequer scope `agents:predict`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 8000 }, "conversation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Se enviado, continua uma conversa existente." }, "session_id": { "type": "string", "maxLength": 200, "nullable": true, "description": "ID livre do canal externo (ex.: chat_id do Telegram). Se enviado, reaproveita/cria a conversa por sessão." }, "stream": { "type": "boolean", "description": "Se true, retorna `text/event-stream` em vez de JSON." }, "metadata": { "type": "object", "description": "Metadados livres gravados na conversa (channel, user_name, etc)." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true }, "answer": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "lead": { "type": "object", "properties": { "requested": { "type": "boolean", "description": "true quando a resposta contém o marcador ." } } } } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE stream com eventos meta/token/done/error." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/skills": { "get": { "tags": [ "Skills" ], "summary": "Listar skills", "description": "Lista as skills da empresa. Requer plugin `skills` ativo e scope `skills:read`.", "parameters": [ { "name": "visibility", "in": "query", "schema": { "type": "string", "enum": [ "free", "locked", "hidden" ] } }, { "name": "published", "in": "query", "schema": { "type": "boolean" }, "description": "Filtra por is_published." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Busca por nome (ilike)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Maximum items to return (default 50, max 200)." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Pagination cursor — pass `next_cursor` from the previous response." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "next_cursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Skills" ], "summary": "Criar skill", "description": "Requer scope `skills:write`, plugin `skills` ativo e key criada por owner/admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Skill" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/v1/skills/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Skills" ], "summary": "Obter skill", "description": "Retorna a skill (inclui skill_md). Requer scope `skills:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Skill" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Skills" ], "summary": "Atualizar skill", "description": "Aceita qualquer subconjunto de campos de SkillCreate. Requer scope `skills:write` e role owner/admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCreate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Skill" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Skills" ], "summary": "Excluir skill", "description": "Requer scope `skills:write` e role owner/admin.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean" } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/mcp": { "post": { "tags": [ "MCP" ], "summary": "MCP server (Streamable HTTP)", "description": "Endpoint Model Context Protocol. Expõe as mesmas operações da API REST como tools MCP: `list_agents`, `get_agent`, `create_agent`, `update_agent`, `delete_agent`, `send_agent_message`, `list_conversations`, `list_messages`, `list_skills`, `get_skill`, `create_skill`, `update_skill`, `delete_skill`. Configure em clientes MCP (Claude Desktop, Cursor, etc) com a URL `/api/public/mcp` e header `Authorization: Bearer am_live_...`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 payload do MCP." } } } }, "responses": { "200": { "description": "JSON-RPC response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — missing scope or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }