{"openapi":"3.1.0","info":{"title":"Top.gg (BYOK) API","version":"0.1.0","description":"Top.gg (BYOK) lets an AI assistant read your own Top.gg data through the Top.gg API with a key you supply (Top.gg project API token (or OAuth/application token)). Read-only: 6 tools (get_project, list_projects, list_votes, get_user_vote_status, get_authorized_user, list_authorized_user_projects). 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-topgg.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-topgg/docs"},"termsOfService":"https://connectorbay.com/byok-topgg/terms"},"servers":[{"url":"https://byok-topgg.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-topgg/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_project":{"post":{"operationId":"get_project","summary":"Get a Top.gg listing (bot, server or game): name, platform, headline, tags, current and all-time votes, review score and","description":"Get a Top.gg listing (bot, server or game): name, platform, headline, tags, current and all-time votes, review score and review count. Use for \"How many votes and reviews does my Top.gg listing have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Top.gg project ID (a number such as '218109768489992192'). With a project token use the literal '@me'; with an OAuth or application token use the real ID.","maxLength":40,"title":"Project Id","type":"string"}},"required":["project_id"],"title":"get_projectArguments","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_projects":{"post":{"operationId":"list_projects","summary":"List the listings an OAuth or application token covers (100 per page). Not available with a single project token. Use fo","description":"List the listings an OAuth or application token covers (100 per page). Not available with a single project token. Use for \"Which Top.gg listings does my application token cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; keep paging until it is absent.","title":"Cursor"}},"title":"list_projectsArguments","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_votes":{"post":{"operationId":"list_votes","summary":"List votes for a listing, oldest first, with voter IDs, vote weight and when each voter can vote again. Needs start_date","description":"List votes for a listing, oldest first, with voter IDs, vote weight and when each voter can vote again. Needs start_date or a cursor; start_date may be at most one year back. Use for \"Who voted for my Top.gg listing since the start of 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Top.gg project ID (a number such as '218109768489992192'). With a project token use the literal '@me'; with an OAuth or application token use the real ID.","maxLength":40,"title":"Project Id","type":"string"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"ISO 8601 time to start from, for example 2026-01-01T00:00:00Z (needed when no cursor is given).","title":"Start Date"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer for the next page; takes precedence over start_date.","title":"Cursor"}},"required":["project_id"],"title":"list_votesArguments","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_vote_status":{"post":{"operationId":"get_user_vote_status","summary":"Check whether one user has an active vote on a listing: returns when they last voted, when they can vote again and the v","description":"Check whether one user has an active vote on a listing: returns when they last voted, when they can vote again and the vote weight; not found if they have not voted. Use for \"Has Discord user 1234567890 voted for my Top.gg listing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Top.gg project ID (a number such as '218109768489992192'). With a project token use the literal '@me'; with an OAuth or application token use the real ID.","maxLength":40,"title":"Project Id","type":"string"},"user_id":{"description":"User ID in the format named by source, for example '1234567890'.","maxLength":30,"title":"User Id","type":"string"},"source":{"anyOf":[{"enum":["topgg","discord"],"type":"string"},{"type":"null"}],"default":"topgg","description":"Which ID type user_id is: topgg (default) or discord.","title":"Source"}},"required":["project_id","user_id"],"title":"get_user_vote_statusArguments","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_authorized_user":{"post":{"operationId":"get_authorized_user","summary":"Show the Top.gg user behind an OAuth access token: ID, username, avatar and linked platform accounts. Needs the user.ide","description":"Show the Top.gg user behind an OAuth access token: ID, username, avatar and linked platform accounts. Needs the user.identify scope. Use for \"Which Top.gg user authorized this token\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_authorized_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/list_authorized_user_projects":{"post":{"operationId":"list_authorized_user_projects","summary":"List the listings owned by the user behind an OAuth access token. Needs the user.projects.read scope. Use for \"Which Top","description":"List the listings owned by the user behind an OAuth access token. Needs the user.projects.read scope. Use for \"Which Top.gg listings does the authorizing user own\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_authorized_user_projectsArguments","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}}}}