{"openapi":"3.1.0","info":{"title":"Be Agent API","version":"1.0.0","description":"API para servidores externos. Guía completa en /docs."},"servers":[{"url":"https://agents.begraffic.com","description":"Producción"},{"url":"/","description":"Entorno actual (desarrollo o pruebas)"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/me":{"get":{"operationId":"workspace","description":"Requiere workspace:read.","responses":{"200":{"description":"Workspace autorizado"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents":{"get":{"operationId":"list_agents","description":"Requiere agents:read. Orden por ID. Continúa mientras next_cursor no sea null, incluso si data está vacío. Campos: id, name, status, publishedVersion, publishedVersionId, createdAt, updatedAt.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de recursos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents/{id}":{"get":{"operationId":"get_agents","description":"Requiere agents:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recurso"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts":{"get":{"operationId":"list_contacts","description":"Requiere contacts:read. Orden por ID. Continúa mientras next_cursor no sea null, incluso si data está vacío. Campos: id, name, email, phone, company, tags, notes, source, createdAt, updatedAt.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de recursos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_contact","description":"Requiere contacts:write. Idempotencia por workspace y clave/conexión. Cuerpo máximo 16 KB.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}},"responses":{"201":{"description":"Contacto guardado"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}":{"get":{"operationId":"get_contacts","description":"Requiere contacts:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recurso"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_contact","description":"Requiere contacts:write. Idempotencia por workspace y clave/conexión. Cuerpo máximo 16 KB.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPatch"}}}},"responses":{"200":{"description":"Contacto guardado"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/leads":{"get":{"operationId":"list_leads","description":"Requiere leads:read. Orden por ID. Continúa mientras next_cursor no sea null, incluso si data está vacío. Campos: id, contactId, title, stage, score, value, source, createdAt, updatedAt.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de recursos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/leads/{id}":{"get":{"operationId":"get_leads","description":"Requiere leads:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recurso"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations":{"get":{"operationId":"list_conversations","description":"Requiere conversations:read. Orden por ID. Continúa mientras next_cursor no sea null, incluso si data está vacío. Campos: id, contactId, agentId, channel, state, lastMessage, lastMessageAt, createdAt, updatedAt.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de recursos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/conversations/{id}":{"get":{"operationId":"get_conversations","description":"Requiere conversations:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recurso"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/appointments":{"get":{"operationId":"list_appointments","description":"Requiere calendar:read. Orden por ID. Continúa mientras next_cursor no sea null, incluso si data está vacío. Campos: id, contactId, title, status, startAt, endAt, timezone, createdAt, updatedAt.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de recursos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/appointments/{id}":{"get":{"operationId":"get_appointments","description":"Requiere calendar:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recurso"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tasks":{"get":{"operationId":"list_tasks","description":"Requiere tasks:read. Orden por ID. Continúa mientras next_cursor no sea null, incluso si data está vacío. Campos: id, contactId, title, status, dueAt, createdAt, updatedAt.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de recursos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tasks/{id}":{"get":{"operationId":"get_tasks","description":"Requiere tasks:read.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recurso"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks":{"get":{"operationId":"list_webhooks","description":"Requiere webhooks:manage. Solo los destinos de esta clave o conexión.","responses":{"200":{"description":"Destinos"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_webhook","description":"Requiere webhooks:manage. Idempotency-Key opcional (16–128 caracteres A-Z a-z 0-9 _ -). Misma conexión, clave y payload recuperan ID y signingSecret cifrado; cambio de payload o destino revocado devuelve 409. Sin clave crea un destino nuevo.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}}},"responses":{"201":{"description":"Destino creado y signingSecret"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}":{"delete":{"operationId":"revoke_webhook","description":"Requiere webhooks:manage. Solo destinos de esta conexión.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Desactivado"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}/test":{"post":{"operationId":"test_webhook","description":"Requiere webhooks:manage. Solo destinos de esta conexión. La respuesta confirma encolado, no entrega.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Prueba encolada"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/oauth/token":{"post":{"security":[],"description":"Canje con código + PKCE S256, o renovación de un solo uso. client_id y client_secret obligatorios.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_id","client_secret","grant_type"],"properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"code":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"code_verifier":{"type":"string","minLength":43,"maxLength":128},"refresh_token":{"type":"string"}},"oneOf":[{"required":["code","redirect_uri","code_verifier"],"properties":{"grant_type":{"const":"authorization_code"}}},{"required":["refresh_token"],"properties":{"grant_type":{"const":"refresh_token"}}}]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["client_id","client_secret","grant_type"],"properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"code":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"code_verifier":{"type":"string","minLength":43,"maxLength":128},"refresh_token":{"type":"string"}},"oneOf":[{"required":["code","redirect_uri","code_verifier"],"properties":{"grant_type":{"const":"authorization_code"}}},{"required":["refresh_token"],"properties":{"grant_type":{"const":"refresh_token"}}}]}}}},"responses":{"200":{"description":"Resultado OAuth","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"const":"Bearer"},"expires_in":{"type":"integer"},"refresh_expires_in":{"type":"integer"},"scope":{"type":"string"},"workspace_id":{"type":"string"},"connection_id":{"type":"string"}}}}}},"400":{"description":"Error OAuth","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"401":{"description":"Error OAuth","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"429":{"description":"Error OAuth","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"500":{"description":"Error OAuth","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}}}},"/api/oauth/revoke":{"post":{"security":[],"description":"Revoca un token de acceso o renovación. client_id y client_secret obligatorios.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_id","client_secret","token"],"properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"token":{"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["client_id","client_secret","token"],"properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Resultado OAuth","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"}}}}}},"400":{"description":"Error OAuth","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"401":{"description":"Error OAuth","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"429":{"description":"Error OAuth","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"500":{"description":"Error OAuth","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}}}},"/api/v1/actions":{"get":{"operationId":"action_catalog","description":"Requiere agents:read. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[],"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ActionCatalog"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents/{agentId}/actions":{"get":{"operationId":"agent_action_catalog","description":"Requiere agents:read. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ActionCatalog"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents/{agentId}/actions/{actionId}":{"post":{"operationId":"execute_agent_action","description":"Requiere actions:execute. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"actionId","in":"path","required":true,"schema":{"type":"string","enum":["searchKnowledge","findContact","createContact","createLead","updateLead","checkAvailability","bookAppointment","rescheduleAppointment","cancelAppointment","createTask","notifyOwner","transferCall"]}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"contact_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,120}$"},"conversation_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,120}$"}},"required":["input"],"additionalProperties":false}}}},"responses":{"202":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ActionExecution"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/action-executions/{id}":{"get":{"operationId":"action_execution_status","description":"Requiere actions:execute. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ActionExecution"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents/{agentId}/action-provider":{"get":{"operationId":"get_action_provider","description":"Requiere actions:manage. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"set_action_provider","description":"Requiere actions:manage webhooks:manage. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"webhook_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,160}$"},"actions":{"maxItems":11,"type":"array","items":{"type":"string","enum":["findContact","createContact","createLead","updateLead","checkAvailability","bookAppointment","rescheduleAppointment","cancelAppointment","createTask","notifyOwner","transferCall"]}}},"required":["webhook_id","actions"],"additionalProperties":false}}}},"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"revoke_action_provider","description":"Requiere actions:manage. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents/{agentId}/runs":{"post":{"operationId":"invoke_agent","description":"Requiere agents:invoke. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4000},"context":{"type":"object","properties":{"conversation_id":{"type":"string","minLength":1,"maxLength":160},"contact_id":{"type":"string","minLength":1,"maxLength":120},"contact_name":{"type":"string","minLength":1,"maxLength":80},"resources":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["lead","appointment"]},"id":{"type":"string","minLength":1,"maxLength":120},"title":{"type":"string","minLength":1,"maxLength":140},"status":{"type":"string","maxLength":40},"date":{"type":"string","maxLength":10},"time":{"type":"string","maxLength":5}},"required":["type","id","title"],"additionalProperties":false}},"education":{"type":"object","properties":{"contract_version":{"type":"string","const":"education.v1"},"school_id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"course_id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"student_id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"mode":{"type":"string","enum":["support","tutor","assessment","community","followup","teacher","admissions"]},"sources":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"title":{"type":"string","minLength":1,"maxLength":160},"text":{"type":"string","minLength":1,"maxLength":12000},"version":{"type":"string","minLength":1,"maxLength":120}},"required":["id","title","text","version"],"additionalProperties":false}},"submission":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"text":{"type":"string","minLength":1,"maxLength":20000}},"required":["id","text"],"additionalProperties":false},"rubric":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"label":{"type":"string","minLength":1,"maxLength":160},"instructions":{"type":"string","minLength":1,"maxLength":2000},"max_points":{"type":"number","exclusiveMinimum":0,"maximum":1000}},"required":["id","label","instructions","max_points"],"additionalProperties":false}}},"required":["contract_version","school_id","course_id","student_id","mode","sources"],"additionalProperties":false},"channel":{"default":"text","type":"string","enum":["text","call","voice_note","email","comment"]}},"required":["conversation_id"],"additionalProperties":false}},"required":["text","context"],"additionalProperties":false}}}},"responses":{"202":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AgentRun"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-runs/{runId}":{"get":{"operationId":"agent_run_status","description":"Requiere agents:invoke. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AgentRun"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-runs/{runId}/results":{"post":{"operationId":"submit_action_results","description":"Requiere actions:results agents:invoke. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"results":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,160}$"},"status":{"type":"string","enum":["succeeded","failed","unknown_outcome"]},"summary":{"type":"string","minLength":1,"maxLength":2000},"data":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["request_id","status","summary"],"additionalProperties":false}}},"required":["results"],"additionalProperties":false}}}},"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AgentRun"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-runs/{runId}/requests/{requestId}/decision":{"post":{"operationId":"decide_action","description":"Requiere actions:approve agents:invoke. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["decision","reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AgentRun"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-runs/{runId}/reconcile":{"post":{"operationId":"reconcile_action_results","description":"Requiere actions:approve actions:results agents:invoke. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"results":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,160}$"},"status":{"type":"string","enum":["succeeded","failed","unknown_outcome"]},"summary":{"type":"string","minLength":1,"maxLength":2000},"data":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["request_id","status","summary"],"additionalProperties":false}}},"required":["results"],"additionalProperties":false}}}},"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AgentRun"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-runs/{runId}/close":{"post":{"operationId":"close_agent_run","description":"Requiere actions:approve agents:invoke. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["decision","reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AgentRun"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-runs/{runId}/retry":{"post":{"operationId":"retry_agent_reasoning","description":"Requiere agents:invoke. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AgentRun"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-runs/{runId}/resume-conversation":{"post":{"operationId":"resume_agent_conversation","description":"Requiere actions:approve agents:invoke. Guía y reglas de efectos, aprobación e idempotencia en /docs.md. IDs locales para ejecución directa; IDs externos para runs.","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]},"reason":{"type":"string","minLength":1,"maxLength":1000}},"required":["decision","reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Resultado; consulta status antes de confirmar efectos.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clave bga_ o access_token de Be Agent Connect. Permisos: workspace:read, agents:read, contacts:read, contacts:write, leads:read, conversations:read, calendar:read, tasks:read, webhooks:manage, agents:invoke, actions:execute, actions:manage, actions:results, actions:approve"}},"schemas":{"AgentRun":{"type":"object","required":["id","agent_id","version_id","status","reply","action_requests","action_history"],"properties":{"id":{"type":"string"},"agent_id":{"type":"string"},"version_id":{"type":"string","description":"Versión del agente de entrada asignado a la cuenta."},"responding_agent_id":{"type":"string","description":"Agente que está atendiendo o respondió; puede ser un especialista autorizado."},"responding_version_id":{"type":"string"},"handoffs":{"type":"array","items":{"type":"object","required":["from_agent_id","to_agent_id","version_id","reason","summary"],"properties":{"from_agent_id":{"type":"string"},"to_agent_id":{"type":"string"},"version_id":{"type":"string"},"reason":{"type":"string"},"summary":{"type":"string"}}}},"status":{"type":"string","enum":["ready","processing","waiting_results","waiting_approval","completed","requires_review","cancelled"]},"reply":{"type":["string","null"]},"education_response":{"anyOf":[{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"contract_version":{"type":"string","const":"education.v1"},"reply":{"type":"string","minLength":1,"maxLength":6000},"citations":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"source_id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"quote":{"type":"string","minLength":1,"maxLength":800}},"required":["source_id","quote"],"additionalProperties":false}},"uncertainty":{"type":"string","enum":["low","medium","high"]},"missing_information":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}},"requires_human_review":{"type":"boolean"},"assessment":{"anyOf":[{"type":"object","properties":{"submission_id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"criteria":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"criterion_id":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[A-Za-z0-9_-]+$"},"suggested_points":{"type":"number","minimum":0,"maximum":1000},"feedback":{"type":"string","minLength":1,"maxLength":2000}},"required":["criterion_id","suggested_points","feedback"],"additionalProperties":false}},"suggested_total":{"type":"number","minimum":0,"maximum":20000}},"required":["submission_id","criteria","suggested_total"],"additionalProperties":false},{"type":"null"}]},"sources":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"string"},"version":{"type":"string"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["source_id","version","sha256"],"additionalProperties":false}}},"required":["contract_version","reply","citations","uncertainty","missing_information","requires_human_review","assessment","sources"],"additionalProperties":false},{"type":"null"}],"description":"Sugerencia education.v1; sources añade source_id/version/sha256 calculados por servidor. Evaluación/comunidad/profesor/seguimiento siempre requieren revisión humana; School decide automatización del resto."},"action_requests":{"type":"array","items":{"$ref":"#/components/schemas/ActionRequest"}},"action_history":{"type":"array","items":{"$ref":"#/components/schemas/ActionRequest"}},"usage":{"type":["object","null"]},"error":{"type":["string","null"]}}},"ActionRequest":{"type":"object","required":["id","action","input","status","requires_approval"],"properties":{"id":{"type":"string"},"action":{"type":"string"},"input":{"type":"object"},"status":{"type":"string","enum":["pending","pending_approval","succeeded","failed","unknown_outcome","rejected"]},"requires_approval":{"type":"boolean"},"result":{"type":"object","properties":{"status":{"type":"string"},"summary":{"type":"string"},"data":{"type":"object"}}}}},"ActionExecution":{"type":"object","required":["id","status","result"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing","success","failed","pending_approval","unknown_outcome","rejected","expired"]},"result":{"type":["object","null"]},"approval_id":{"type":["string","null"]}}},"ActionCatalog":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"input_schema":{"type":["object","null"]},"external_result_schema":{"type":["object","null"]},"available":{"type":"boolean"},"can_delegate":{"type":"boolean"},"enabled":{"type":"boolean"},"requires_approval":{"type":"boolean"},"external_provider":{"type":"boolean"}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ContactInput":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","format":"email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"company":{"type":"string","maxLength":120},"tags":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":40}},"notes":{"type":"string","maxLength":4000}}},"ContactPatch":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","format":"email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"company":{"type":"string","maxLength":120},"tags":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":40}},"notes":{"type":"string","maxLength":4000}}},"WebhookInput":{"type":"object","additionalProperties":false,"required":["name","url","events"],"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"url":{"type":"string","format":"uri","maxLength":2048},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["contact.created","contact.updated","lead.created","appointment.created","appointment.cancelled","conversation.ended","task.overdue","agent.action.requested","agent.run.completed"]}}}}}}}