{"openapi":"3.1.0","info":{"title":"Botpress (BYOK) API","version":"0.1.0","description":"Botpress (BYOK) lets an AI assistant read your own Botpress data through the Botpress API with a key you supply (Botpress personal access token). Read-only: 8 tools (get_account, list_workspaces, get_workspace, get_workspace_quota, list_bots, get_bot_analytics, list_bot_issues, list_integrations). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-botpress.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-botpress/docs"},"termsOfService":"https://connectorbay.com/byok-botpress/terms"},"servers":[{"url":"https://byok-botpress.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-botpress/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_account":{"post":{"operationId":"get_account","summary":"Show the Botpress account behind the token: id, display name, email verification flag and creation time. The email addre","description":"Show the Botpress account behind the token: id, display name, email verification flag and creation time. The email address is not requested. Use for \"Which Botpress account is this token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_accountArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_workspaces":{"post":{"operationId":"list_workspaces","summary":"List the workspaces the account can access with plan, bot count, spending limit, blocked flag and creation time. Use for","description":"List the workspaces the account can access with plan, bot count, spending limit, blocked flag and creation time. Use for \"Which Botpress workspaces do I have and on which plan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"handle":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the workspace with this public handle.","title":"Handle"},"next_token":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Token from meta.nextToken of the previous answer, for the next page.","title":"Next Token"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items per page (1 to 100).","title":"Page Size"}},"title":"list_workspacesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_workspace":{"post":{"operationId":"get_workspace","summary":"Get one workspace: name, plan, bot count, spending limit, blocked flag, handle and times. Use for \"How many bots does Bo","description":"Get one workspace: name, plan, bot count, spending limit, blocked flag, handle and times. Use for \"How many bots does Botpress workspace X have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Id of the workspace, from list_workspaces.","maxLength":100,"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"get_workspaceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_workspace_quota":{"post":{"operationId":"get_workspace_quota","summary":"Get one quota of a workspace (for example bot_count, ai_spend, storage_count or invocation_calls) for a billing period. ","description":"Get one quota of a workspace (for example bot_count, ai_spend, storage_count or invocation_calls) for a billing period. Use for \"How much AI spend has my Botpress workspace used this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Id of the workspace, from list_workspaces.","maxLength":100,"title":"Workspace Id","type":"string"},"type":{"description":"Quota to read.","enum":["invocation_timeout","invocation_calls","storage_count","bot_count","knowledgebase_vector_storage","workspace_ratelimit","table_row_count","workspace_member_count","integrations_owned_count","ai_spend","openai_spend","bing_search_spend","always_alive","indexed_file_count","file_max_size_bytes"],"title":"Type","type":"string"},"period":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Billing period such as 2026-10; leave empty for the current one.","title":"Period"}},"required":["workspace_id","type"],"title":"get_workspace_quotaArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_bots":{"post":{"operationId":"list_bots","summary":"List the bots of the workspace in the x-workspace-id header with name, type, tags, creation and deployment time. Use for","description":"List the bots of the workspace in the x-workspace-id header with name, type, tags, creation and deployment time. Use for \"Which Botpress bots do I have and when were they last deployed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort_field":{"anyOf":[{"enum":["createdAt","updatedAt"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by createdAt or updatedAt.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"asc or desc.","title":"Sort Direction"},"dev":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only development bots.","title":"Dev"},"next_token":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Token from meta.nextToken of the previous answer, for the next page.","title":"Next Token"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items per page (1 to 100).","title":"Page Size"}},"title":"list_botsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_bot_analytics":{"post":{"operationId":"get_bot_analytics","summary":"Get daily usage analytics of a bot for a date range: new and returning users, sessions, messages and conversations creat","description":"Get daily usage analytics of a bot for a date range: new and returning users, sessions, messages and conversations created. Use for \"How many sessions did my Botpress bot have last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bot_id":{"description":"Id of the bot, from list_bots.","maxLength":200,"title":"Bot Id","type":"string"},"start_date":{"description":"First day, ISO 8601, for example 2026-10-01.","maxLength":40,"title":"Start Date","type":"string"},"end_date":{"description":"Last day, ISO 8601, for example 2026-10-07.","maxLength":40,"title":"End Date","type":"string"}},"required":["bot_id","start_date","end_date"],"title":"get_bot_analyticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_bot_issues":{"post":{"operationId":"list_bot_issues","summary":"List the issues Botpress detected for a bot (code errors, limits, configuration) with title, category, count and last se","description":"List the issues Botpress detected for a bot (code errors, limits, configuration) with title, category, count and last seen time. Use for \"Which problems does Botpress report for my bot\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bot_id":{"description":"Id of the bot, from list_bots.","maxLength":200,"title":"Bot Id","type":"string"},"next_token":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Token from meta.nextToken of the previous answer, for the next page.","title":"Next Token"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items per page (1 to 100).","title":"Page Size"}},"required":["bot_id"],"title":"list_bot_issuesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_integrations":{"post":{"operationId":"list_integrations","summary":"List integrations available to the workspace with name, version, title, description, visibility and verification status.","description":"List integrations available to the workspace with name, version, title, description, visibility and verification status. Use for \"Which integrations can I install in Botpress\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only integrations matching this text.","title":"Search"},"visibility":{"anyOf":[{"enum":["public","private"],"type":"string"},{"type":"null"}],"default":null,"description":"Only public or private integrations.","title":"Visibility"},"sort_by":{"anyOf":[{"enum":["popularity","name","createdAt","updatedAt","installCount"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by popularity, name, createdAt, updatedAt or installCount.","title":"Sort By"},"next_token":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Token from meta.nextToken of the previous answer, for the next page.","title":"Next Token"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items per page (1 to 100).","title":"Page Size"}},"title":"list_integrationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}