{"openapi":"3.0.0","info":{"title":"AgentBrink API","version":"1.0.0","description":"AI agent identity and services platform. Provides email, SMS, Telegram, webhooks, secrets vault, persistent memory, and skills for autonomous agents.","contact":{"name":"AgentBrink","url":"https://agentbrink.com"}},"servers":[{"url":"/api","description":"Management API (agent/org CRUD)"},{"url":"/sdk","description":"SDK API (agent runtime — requires Bearer API key)"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT or API key","description":"Use your AgentBrink API key: `Authorization: Bearer ab_xxx`"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"Not found"}}},"Organization":{"type":"object","properties":{"_id":{"type":"string","example":"65f1a2b3c4d5e6f7a8b9c0d1"},"name":{"type":"string","example":"Acme Corp"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateOrganizationBody":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Acme Corp"}}},"Agent":{"type":"object","properties":{"_id":{"type":"string","example":"65f1a2b3c4d5e6f7a8b9c0d1"},"name":{"type":"string","example":"MyBot"},"organizationId":{"type":"string"},"systemPrompt":{"type":"string"},"mode":{"type":"string","enum":["sdk","managed"],"example":"sdk"},"status":{"type":"string","enum":["pending","ready","error"],"example":"ready"},"email":{"type":"string","format":"email","example":"mybot@agentbrink.com"},"phone":{"type":"string","example":"+14155552671"},"enabledIntegrations":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateAgentBody":{"type":"object","required":["name","organizationId"],"properties":{"name":{"type":"string","example":"MyBot"},"organizationId":{"type":"string"},"systemPrompt":{"type":"string"},"mode":{"type":"string","enum":["sdk","managed"],"default":"sdk"},"githubUsername":{"type":"string","example":"acme"}}},"UpdateAgentBody":{"type":"object","properties":{"name":{"type":"string"},"systemPrompt":{"type":"string"},"mode":{"type":"string","enum":["sdk","managed"]}}},"EnableIntegrationBody":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["telegram","email","sms","github"],"example":"telegram"},"config":{"type":"object","description":"Integration-specific config (e.g. botToken for Telegram)","additionalProperties":true}}},"StoreCredentialBody":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string","example":"TELEGRAM_BOT_TOKEN"},"value":{"type":"string","example":"bot123:abc"}}},"Message":{"type":"object","properties":{"_id":{"type":"string"},"agentId":{"type":"string"},"channel":{"type":"string","enum":["telegram","email","sms","webhook"]},"direction":{"type":"string","enum":["inbound","outbound"]},"externalChatId":{"type":"string"},"conversationId":{"type":"string"},"content":{"type":"object","properties":{"type":{"type":"string","example":"text"},"text":{"type":"string"}}},"status":{"type":"string","enum":["pending","delivered","failed"]},"createdAt":{"type":"string","format":"date-time"}}},"SendMessageBody":{"type":"object","required":["channel","externalChatId","content"],"properties":{"channel":{"type":"string","enum":["telegram","email","sms"]},"externalChatId":{"type":"string","description":"Telegram chat ID, email address, or phone number"},"conversationId":{"type":"string"},"content":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","example":"text"},"text":{"type":"string","example":"Hello!"}}}}},"Secret":{"type":"object","properties":{"key":{"type":"string","example":"OPENAI_API_KEY"},"value":{"type":"string","example":"sk-..."}}},"SetSecretBody":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string","example":"OPENAI_API_KEY"},"value":{"type":"string","example":"sk-..."}}},"MemoryFact":{"type":"object","properties":{"key":{"type":"string","example":"user_name"},"value":{"type":"string","example":"Alice"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"StoreFactBody":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string","example":"user_name"},"value":{"type":"string","example":"Alice"}}},"SkillParameter":{"type":"object","required":["name","type","description"],"properties":{"name":{"type":"string","example":"city"},"type":{"type":"string","enum":["string","number","boolean","object","array"]},"description":{"type":"string","example":"City name"},"required":{"type":"boolean","default":false}}},"SkillHandler":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["webhook","mcp"]},"webhookUrl":{"type":"string","description":"For webhook handlers: URL to POST to","example":"https://example.com/weather"},"webhookHeaders":{"type":"object","description":"Optional extra headers for webhook calls","additionalProperties":{"type":"string"}},"mcpServerUrl":{"type":"string","description":"For MCP handlers: HTTP base URL of the MCP server","example":"http://localhost:3001"},"mcpToolName":{"type":"string","description":"For MCP handlers: tool name to call on the MCP server","example":"search"}}},"Skill":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string","example":"get_weather"},"description":{"type":"string","example":"Get current weather for a city"},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/SkillParameter"}},"handler":{"$ref":"#/components/schemas/SkillHandler"},"enabled":{"type":"boolean","default":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"UpsertSkillBody":{"type":"object","required":["name","description","handler"],"properties":{"name":{"type":"string","example":"get_weather"},"description":{"type":"string","example":"Get current weather for a city"},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/SkillParameter"}},"handler":{"$ref":"#/components/schemas/SkillHandler"},"enabled":{"type":"boolean","default":true}}},"InvokeSkillBody":{"type":"object","description":"Arbitrary key-value arguments to pass to the skill","additionalProperties":true,"example":{"city":"Tel Aviv"}},"InvokeSkillResponse":{"type":"object","properties":{"success":{"type":"boolean"},"output":{},"error":{"type":"string"}}},"AgentConfig":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"mode":{"type":"string","enum":["sdk","managed"]},"status":{"type":"string"},"webhookUrl":{"type":"string"},"enabledIntegrations":{"type":"array","items":{"type":"string"}}}}},"parameters":{"agentId":{"name":"agentId","in":"path","required":true,"schema":{"type":"string"},"description":"Agent MongoDB ObjectId"},"orgId":{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},"secretKey":{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"Secret key name"},"factKey":{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"Memory fact key"},"skillName":{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"Skill name (unique per agent)"}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{"BearerAuth":[]}],"paths":{"/api/orgs":{"get":{"tags":["Organizations"],"summary":"List organizations","responses":{"200":{"description":"Array of organizations","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Organization"}}}}}}},"post":{"tags":["Organizations"],"summary":"Create an organization","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/orgs/{orgId}":{"parameters":[{"$ref":"#/components/parameters/orgId"}],"get":{"tags":["Organizations"],"summary":"Get organization by ID","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Organizations"],"summary":"Update an organization","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Organizations"],"summary":"Delete an organization","responses":{"200":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agents":{"get":{"tags":["Agents"],"summary":"List all agents","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}}}},"post":{"tags":["Agents"],"summary":"Create an agent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/agents/{agentId}":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"get":{"tags":["Agents"],"summary":"Get agent by ID","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Agents"],"summary":"Update an agent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Agents"],"summary":"Delete an agent","responses":{"200":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agents/{agentId}/integrations":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"post":{"tags":["Agents"],"summary":"Enable an integration for an agent (telegram, email, sms, github)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnableIntegrationBody"}}}},"responses":{"200":{"description":"Integration enabled"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agents/{agentId}/integrations/{type}":{"parameters":[{"$ref":"#/components/parameters/agentId"},{"name":"type","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"tags":["Agents"],"summary":"Disable an integration","responses":{"200":{"description":"Integration disabled"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agents/{agentId}/credentials":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"get":{"tags":["Agents"],"summary":"List credential keys (values are never returned)","responses":{"200":{"description":"Array of key names","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}}}},"post":{"tags":["Agents"],"summary":"Store an encrypted credential","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCredentialBody"}}}},"responses":{"200":{"description":"Stored"},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/agents/{agentId}/credentials/{key}":{"parameters":[{"$ref":"#/components/parameters/agentId"},{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"tags":["Agents"],"summary":"Delete a credential","responses":{"200":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agents/{agentId}/api-key/regenerate":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"post":{"tags":["Agents"],"summary":"Regenerate the agent API key","responses":{"200":{"description":"New API key","content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"string"}}}}}}}}},"/api/agents/{agentId}/redeploy":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"post":{"tags":["Agents"],"summary":"Redeploy the agent (push to GitHub repo)","responses":{"200":{"description":"Redeployed"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agents/{agentId}/memory/facts":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"get":{"tags":["Memory (Admin)"],"summary":"List all memory facts for an agent","responses":{"200":{"description":"Array of facts","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MemoryFact"}}}}}}},"post":{"tags":["Memory (Admin)"],"summary":"Store a memory fact","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreFactBody"}}}},"responses":{"200":{"description":"Stored"}}}},"/api/agents/{agentId}/memory/facts/{key}":{"parameters":[{"$ref":"#/components/parameters/agentId"},{"$ref":"#/components/parameters/factKey"}],"get":{"tags":["Memory (Admin)"],"summary":"Get a memory fact by key","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryFact"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Memory (Admin)"],"summary":"Delete a memory fact","responses":{"200":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sdk/agents/{agentId}/messages":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"get":{"tags":["SDK — Messages"],"summary":"Poll inbound messages (check_messages)","description":"Returns recent inbound messages across all channels. Used by agents on a polling loop.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":100},"description":"Max messages to return"},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Return messages after this timestamp"}],"responses":{"200":{"description":"Array of messages","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["SDK — Messages"],"summary":"Send a message (send_message)","description":"Send a message from the agent to a user on telegram, email, or sms.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageBody"}}}},"responses":{"200":{"description":"Message queued","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"sent"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/sdk/agents/{agentId}/config":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"get":{"tags":["SDK — Identity"],"summary":"Get agent identity config (get_identity)","description":"Returns the full agent identity: email, phone, webhook URLs, GitHub repo, status.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentConfig"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sdk/agents/{agentId}/secrets/{key}":{"parameters":[{"$ref":"#/components/parameters/agentId"},{"$ref":"#/components/parameters/secretKey"}],"get":{"tags":["SDK — Secrets"],"summary":"Get a secret (get_secret)","description":"Retrieve a decrypted secret from the agent vault.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Secret"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sdk/agents/{agentId}/secrets":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"post":{"tags":["SDK — Secrets"],"summary":"Store a secret (set_secret)","description":"Encrypt and store a secret value in the agent vault.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSecretBody"}}}},"responses":{"200":{"description":"Stored","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"key":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/sdk/agents/{agentId}/memory/facts":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"get":{"tags":["SDK — Memory"],"summary":"List all memory facts (get_memory)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MemoryFact"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["SDK — Memory"],"summary":"Store a memory fact (set_memory)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreFactBody"}}}},"responses":{"200":{"description":"Stored"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/sdk/agents/{agentId}/memory/facts/{key}":{"parameters":[{"$ref":"#/components/parameters/agentId"},{"$ref":"#/components/parameters/factKey"}],"get":{"tags":["SDK — Memory"],"summary":"Get memory fact by key","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryFact"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["SDK — Memory"],"summary":"Delete a memory fact","responses":{"200":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sdk/agents/{agentId}/skills":{"parameters":[{"$ref":"#/components/parameters/agentId"}],"get":{"tags":["SDK — Skills"],"summary":"List skills (list_skills)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/sdk/agents/{agentId}/skills/{name}":{"parameters":[{"$ref":"#/components/parameters/agentId"},{"$ref":"#/components/parameters/skillName"}],"get":{"tags":["SDK — Skills"],"summary":"Get a skill by name","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["SDK — Skills"],"summary":"Create or update a skill (upsert)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertSkillBody"}}}},"responses":{"200":{"description":"Upserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Skill"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}},"delete":{"tags":["SDK — Skills"],"summary":"Delete a skill","responses":{"200":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sdk/agents/{agentId}/skills/{name}/invoke":{"parameters":[{"$ref":"#/components/parameters/agentId"},{"$ref":"#/components/parameters/skillName"}],"post":{"tags":["SDK — Skills"],"summary":"Invoke a skill (invoke_skill)","description":"Dispatch a skill call. For webhook handlers, POSTs to the configured URL. For MCP handlers, calls the tool via JSON-RPC 2.0.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeSkillBody"}}}},"responses":{"200":{"description":"Skill result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeSkillResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/hooks/{type}/{agentId}":{"parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["telegram","email","sms","webhook"]}},{"$ref":"#/components/parameters/agentId"}],"post":{"tags":["Inbound Webhooks"],"summary":"Receive inbound webhook from integration provider","description":"Called by Telegram, Telnyx, or external services. No auth required — validate via platform-level secret in the URL.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"OK"}}}}}}