{"openapi":"3.1.0","info":{"title":"esa.io (BYOK) API","version":"0.1.0","description":"esa.io (BYOK) lets an AI assistant read your own esa.io data through the esa.io API with a key you supply (esa personal access token (read scope is enough)). Read-only: 10 tools (list_teams, get_team, get_team_stats, list_members, list_posts, get_post, list_post_comments, list_team_comments, list_tags, get_authenticated_user). The BYOK key travels with each request, is used for that one call only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-esa.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-esa/docs"},"termsOfService":"https://connectorbay.com/byok-esa/terms"},"servers":[{"url":"https://byok-esa.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-esa/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/list_teams":{"post":{"operationId":"list_teams","summary":"List the esa.io teams the token's owner belongs to, optionally only those where the owner is a member or an owner. Use f","description":"List the esa.io teams the token's owner belongs to, optionally only those where the owner is a member or an owner. Use for \"Which esa teams am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"role":{"anyOf":[{"enum":["member","owner"],"type":"string"},{"type":"null"}],"default":null,"description":"Only teams where the user has this role: member or owner.","title":"Role"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100, default 20).","title":"Per Page"}},"title":"list_teamsArguments","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_team":{"post":{"operationId":"get_team","summary":"Get one team: name, privacy (open or closed), description and URL. Use for \"What is the esa team 'docs' about\".","description":"Get one team: name, privacy (open or closed), description and URL. Use for \"What is the esa team 'docs' about\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_name":{"description":"Team name, which is also the subdomain of the team (for example 'docs' for docs.esa.io).","maxLength":200,"title":"Team Name","type":"string"}},"required":["team_name"],"title":"get_teamArguments","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_team_stats":{"post":{"operationId":"get_team_stats","summary":"Get a team's counts of members, posts (total, wip, shipped), comments and stars, plus daily, weekly and monthly active u","description":"Get a team's counts of members, posts (total, wip, shipped), comments and stars, plus daily, weekly and monthly active users. Use for \"How many posts and active users does the esa team 'docs' have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_name":{"description":"Team name, which is also the subdomain of the team (for example 'docs' for docs.esa.io).","maxLength":200,"title":"Team Name","type":"string"}},"required":["team_name"],"title":"get_team_statsArguments","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_members":{"post":{"operationId":"list_members","summary":"List a team's members with role, number of posts, join date and last access time (email addresses are not returned). Use","description":"List a team's members with role, number of posts, join date and last access time (email addresses are not returned). Use for \"Who are the most active writers in the esa team 'docs'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_name":{"description":"Team name, which is also the subdomain of the team (for example 'docs' for docs.esa.io).","maxLength":200,"title":"Team Name","type":"string"},"sort":{"anyOf":[{"enum":["posts_count","joined","last_accessed"],"type":"string"},{"type":"null"}],"default":"posts_count","description":"Order by posts_count, joined or last_accessed.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"desc (default) or asc.","title":"Order"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100, default 20).","title":"Per Page"}},"required":["team_name"],"title":"list_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/list_posts":{"post":{"operationId":"list_posts","summary":"List or search a team's posts with title, category, tags, WIP flag, authors, dates and comment and star counts (no body ","description":"List or search a team's posts with title, category, tags, WIP flag, authors, dates and comment and star counts (no body text). Use for \"Which esa posts in the 'docs' team were updated most recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_name":{"description":"Team name, which is also the subdomain of the team (for example 'docs' for docs.esa.io).","maxLength":200,"title":"Team Name","type":"string"},"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"esa search query, for example 'in:dev wip:false @fukayatsu' or plain keywords.","title":"Q"},"sort":{"anyOf":[{"enum":["updated","created","number","stars","watches","comments","best_match"],"type":"string"},{"type":"null"}],"default":"updated","description":"Order by updated, created, number, stars, watches, comments or best_match.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"desc (default) or asc.","title":"Order"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100, default 20).","title":"Per Page"}},"required":["team_name"],"title":"list_postsArguments","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_post":{"post":{"operationId":"get_post","summary":"Get one post including its Markdown body, tags, category, authors, revision number and backlink count. Use for \"Show esa","description":"Get one post including its Markdown body, tags, category, authors, revision number and backlink count. Use for \"Show esa post number 1 in the 'docs' team\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_name":{"description":"Team name, which is also the subdomain of the team (for example 'docs' for docs.esa.io).","maxLength":200,"title":"Team Name","type":"string"},"post_number":{"description":"Post number inside the team (the number in the post URL).","minimum":1,"title":"Post Number","type":"integer"}},"required":["team_name","post_number"],"title":"get_postArguments","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_post_comments":{"post":{"operationId":"list_post_comments","summary":"List the comments on one post, newest update first, with Markdown body, author and star count. Use for \"What comments ar","description":"List the comments on one post, newest update first, with Markdown body, author and star count. Use for \"What comments are on esa post 2 of the 'docs' team\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_name":{"description":"Team name, which is also the subdomain of the team (for example 'docs' for docs.esa.io).","maxLength":200,"title":"Team Name","type":"string"},"post_number":{"description":"Post number inside the team (the number in the post URL).","minimum":1,"title":"Post Number","type":"integer"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100, default 20).","title":"Per Page"}},"required":["team_name","post_number"],"title":"list_post_commentsArguments","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_team_comments":{"post":{"operationId":"list_team_comments","summary":"List comments across the whole team, newest first. Use for \"What are the latest comments in the esa team 'docs'\".","description":"List comments across the whole team, newest first. Use for \"What are the latest comments in the esa team 'docs'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_name":{"description":"Team name, which is also the subdomain of the team (for example 'docs' for docs.esa.io).","maxLength":200,"title":"Team Name","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100, default 20).","title":"Per Page"}},"required":["team_name"],"title":"list_team_commentsArguments","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_tags":{"post":{"operationId":"list_tags","summary":"List a team's tags with the number of posts carrying each, most used first. Use for \"Which tags are used most in the esa","description":"List a team's tags with the number of posts carrying each, most used first. Use for \"Which tags are used most in the esa team 'docs'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_name":{"description":"Team name, which is also the subdomain of the team (for example 'docs' for docs.esa.io).","maxLength":200,"title":"Team Name","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100, default 20).","title":"Per Page"}},"required":["team_name"],"title":"list_tagsArguments","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_authenticated_user":{"post":{"operationId":"get_authenticated_user","summary":"Show the esa account the token belongs to: id, name, screen name and creation date (email is not returned). Use for \"Whi","description":"Show the esa account the token belongs to: id, name, screen name and creation date (email is not returned). Use for \"Which esa account is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_authenticated_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}}}}