{"openapi":"3.1.0","info":{"title":"Stoat (BYOK) API","version":"0.1.0","description":"Stoat (BYOK) lets an AI assistant read your own Stoat data through the Stoat API with a key you supply (Stoat bot token). Read-only: 10 tools (get_server_info, get_self, get_user, get_server, list_server_members, get_channel, get_role, list_server_emoji, list_server_invites, list_server_bans). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-stoat.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-stoat/docs"},"termsOfService":"https://connectorbay.com/byok-stoat/terms"},"servers":[{"url":"https://byok-stoat.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-stoat/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_server_info":{"post":{"operationId":"get_server_info","summary":"Show the Stoat instance's public configuration: API version, which features are on, websocket and app URLs. Use for \"Whi","description":"Show the Stoat instance's public configuration: API version, which features are on, websocket and app URLs. Use for \"Which version of the Stoat API is running\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_server_infoArguments","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_self":{"post":{"operationId":"get_self","summary":"Show the bot user the token belongs to: username, display name, flags, badges and status. Use for \"Which Stoat bot is th","description":"Show the bot user the token belongs to: username, display name, flags, badges and status. Use for \"Which Stoat bot is this token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_selfArguments","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_user":{"post":{"operationId":"get_user","summary":"Get a Stoat user's public information by user ID: username, display name, badges, online flag and status. Use for \"Who i","description":"Get a Stoat user's public information by user ID: username, display name, badges, online flag and status. Use for \"Who is Stoat user 01FD58YK5W7QRV5H3D64KTQYX3\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"Stoat user ID (ULID).","maxLength":40,"title":"User Id","type":"string"}},"required":["user_id"],"title":"get_userArguments","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_server":{"post":{"operationId":"get_server","summary":"Get a server the bot is in: name, description, owner, channel IDs, roles, default permissions and approximate member cou","description":"Get a server the bot is in: name, description, owner, channel IDs, roles, default permissions and approximate member count. Use for \"How many members does my Stoat server have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Stoat server ID (a 26-character ULID such as '01FD58YK5W7QRV5H3D64KTQYX3').","maxLength":40,"title":"Server Id","type":"string"}},"required":["server_id"],"title":"get_serverArguments","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_server_members":{"post":{"operationId":"list_server_members","summary":"List a server's members with join time, nickname and role IDs, plus the user records (username, display name, online fla","description":"List a server's members with join time, nickname and role IDs, plus the user records (username, display name, online flag). Use for \"Who is in my Stoat server and which roles do they have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Stoat server ID (a 26-character ULID such as '01FD58YK5W7QRV5H3D64KTQYX3').","maxLength":40,"title":"Server Id","type":"string"},"exclude_offline":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to leave out offline users.","title":"Exclude Offline"}},"required":["server_id"],"title":"list_server_membersArguments","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_channel":{"post":{"operationId":"get_channel","summary":"Get a channel by ID: type, name, description, server, NSFW flag, slow mode and last message ID (no message text). Use fo","description":"Get a channel by ID: type, name, description, server, NSFW flag, slow mode and last message ID (no message text). Use for \"What is Stoat channel 01FD58YK5W7QRV5H3D64KTQYX5 for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"Stoat channel ID (ULID).","maxLength":40,"title":"Channel Id","type":"string"}},"required":["channel_id"],"title":"get_channelArguments","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_role":{"post":{"operationId":"get_role","summary":"Get one server role: name, color, rank, hoist flag and permission settings. Use for \"What permissions does role 01FD58YK","description":"Get one server role: name, color, rank, hoist flag and permission settings. Use for \"What permissions does role 01FD58YK5W7QRV5H3D64KTQYX6 have in my Stoat server\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Stoat server ID (a 26-character ULID such as '01FD58YK5W7QRV5H3D64KTQYX3').","maxLength":40,"title":"Server Id","type":"string"},"role_id":{"description":"Role ID (ULID), found in the server's roles.","maxLength":40,"title":"Role Id","type":"string"}},"required":["server_id","role_id"],"title":"get_roleArguments","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_server_emoji":{"post":{"operationId":"list_server_emoji","summary":"List a server's custom emoji with name, creator and animated flag. Use for \"What custom emoji does my Stoat server have\"","description":"List a server's custom emoji with name, creator and animated flag. Use for \"What custom emoji does my Stoat server have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Stoat server ID (a 26-character ULID such as '01FD58YK5W7QRV5H3D64KTQYX3').","maxLength":40,"title":"Server Id","type":"string"}},"required":["server_id"],"title":"list_server_emojiArguments","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_server_invites":{"post":{"operationId":"list_server_invites","summary":"List a server's invites with channel, creator, uses and expiry. Use for \"Which invites exist for my Stoat server\".","description":"List a server's invites with channel, creator, uses and expiry. Use for \"Which invites exist for my Stoat server\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Stoat server ID (a 26-character ULID such as '01FD58YK5W7QRV5H3D64KTQYX3').","maxLength":40,"title":"Server Id","type":"string"}},"required":["server_id"],"title":"list_server_invitesArguments","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_server_bans":{"post":{"operationId":"list_server_bans","summary":"List users banned from a server with the ban reason. Use for \"Who is banned from my Stoat server\".","description":"List users banned from a server with the ban reason. Use for \"Who is banned from my Stoat server\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server_id":{"description":"Stoat server ID (a 26-character ULID such as '01FD58YK5W7QRV5H3D64KTQYX3').","maxLength":40,"title":"Server Id","type":"string"}},"required":["server_id"],"title":"list_server_bansArguments","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}}}}