{"openapi":"3.1.0","info":{"title":"Circle (BYOK) API","version":"0.1.0","description":"Circle (BYOK) lets an AI assistant read your own Circle data through the Circle API with a key you supply (Circle Admin API v2 token (Business plan or above)). Read-only: 11 tools (get_community, list_spaces, list_space_groups, list_posts, list_comments, list_events, list_topics, list_member_tags, list_access_groups, list_forms, list_flagged_contents). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-circle.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-circle/docs"},"termsOfService":"https://connectorbay.com/byok-circle/terms"},"servers":[{"url":"https://byok-circle.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-circle/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_community":{"post":{"operationId":"get_community","summary":"Show the community the token belongs to: name, slug, locale, privacy, creation date and digest setting. Use for \"Which C","description":"Show the community the token belongs to: name, slug, locale, privacy, creation date and digest setting. Use for \"Which Circle community is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_communityArguments","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_spaces":{"post":{"operationId":"list_spaces","summary":"List the community's spaces with type, privacy, draft and hidden flags and URL. Use for \"What spaces does our Circle com","description":"List the community's spaces with type, privacy, draft and hidden flags and URL. Use for \"What spaces does our Circle community have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"enum":["active","oldest","alphabetical","likes","latest_updated","oldest_updated"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: active, oldest, alphabetical, likes, latest_updated or oldest_updated.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_spacesArguments","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_space_groups":{"post":{"operationId":"list_space_groups","summary":"List the space groups (sidebar sections) with counts of spaces and members. Use for \"How are our Circle spaces grouped\".","description":"List the space groups (sidebar sections) with counts of spaces and members. Use for \"How are our Circle spaces grouped\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only groups whose name matches this text.","title":"Name"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_space_groupsArguments","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 basic posts with title, status, space, author name, comment and like counts and dates. Use for \"What are the latest","description":"List basic posts with title, status, space, author name, comment and like counts and dates. Use for \"What are the latest posts in our Circle community\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"space_id":{"anyOf":[{"maximum":2000000000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only posts of this space id, from list_spaces.","title":"Space Id"},"status":{"anyOf":[{"enum":["draft","published","scheduled","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Post status: draft, published, scheduled or all.","title":"Status"},"search_text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only posts matching this text.","title":"Search Text"},"sort":{"anyOf":[{"enum":["oldest","latest","alphabetical","likes","latest_updated","oldest_updated"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: oldest, latest, alphabetical, likes, latest_updated or oldest_updated.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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/list_comments":{"post":{"operationId":"list_comments","summary":"List comments with reply and like counts, date and URL; filter by space or post. Comment text is not returned. Use for \"","description":"List comments with reply and like counts, date and URL; filter by space or post. Comment text is not returned. Use for \"How many comments are on Circle post 1001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"space_id":{"anyOf":[{"maximum":2000000000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only comments in this space id.","title":"Space Id"},"post_id":{"anyOf":[{"maximum":2000000000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only comments on this post id, from list_posts.","title":"Post Id"},"search_text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only comments matching this text.","title":"Search Text"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_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_events":{"post":{"operationId":"list_events","summary":"List events with start and end time, location type and like and comment counts. Use for \"What events are coming up in ou","description":"List events with start and end time, location type and like and comment counts. Use for \"What events are coming up in our Circle community\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"space_id":{"anyOf":[{"maximum":2000000000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only events of this event space id.","title":"Space Id"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only events from this date (YYYY-MM-DD); use with end_date.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only events up to this date (YYYY-MM-DD); use with start_date.","title":"End Date"},"sort":{"anyOf":[{"enum":["oldest","start_date","start_date_desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: oldest, start_date or start_date_desc (default newest).","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_eventsArguments","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_topics":{"post":{"operationId":"list_topics","summary":"List the topics used to organize posts. Use for \"Which topics exist in our Circle community\".","description":"List the topics used to organize posts. Use for \"Which topics exist in our Circle community\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only topics whose name matches this text.","title":"Name"},"sort":{"anyOf":[{"enum":["oldest","newest","alphabetical","alphabetical_desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: oldest, newest, alphabetical or alphabetical_desc.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_topicsArguments","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_member_tags":{"post":{"operationId":"list_member_tags","summary":"List member tags with color, visibility and how many members carry each. Use for \"What member tags are in use in Circle\"","description":"List member tags with color, visibility and how many members carry each. Use for \"What member tags are in use in Circle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only tags whose name matches this text.","title":"Name"},"is_public":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for public tags only, false for private ones.","title":"Is Public"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_member_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/list_access_groups":{"post":{"operationId":"list_access_groups","summary":"List access groups (paid or gated member groups) with status and description. Use for \"Which access groups does our Circ","description":"List access groups (paid or gated member groups) with status and description. Use for \"Which access groups does our Circle community have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["active","archived","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Group status: active, archived or all.","title":"Status"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only groups whose name matches this text.","title":"Name"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_access_groupsArguments","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_forms":{"post":{"operationId":"list_forms","summary":"List forms with status and number of submissions. Use for \"What forms do we have in Circle and how many answers did they","description":"List forms with status and number of submissions. Use for \"What forms do we have in Circle and how many answers did they get\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only forms whose name matches this text.","title":"Name"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_formsArguments","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_flagged_contents":{"post":{"operationId":"list_flagged_contents","summary":"List content reported by members for moderation with reason, status and dates. Names and emails are left out. Use for \"I","description":"List content reported by members for moderation with reason, status and dates. Names and emails are left out. Use for \"Is there reported content waiting for moderation in Circle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["all","inbox","approved","rejected"],"type":"string"},{"type":"null"}],"default":null,"description":"Status: all, inbox, approved or rejected.","title":"Status"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_flagged_contentsArguments","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}}}}