{"openapi":"3.1.0","info":{"title":"CircleCI (BYOK) API","version":"0.1.0","description":"CircleCI (BYOK) lets an AI assistant read your own CircleCI data through the CircleCI API with a key you supply (personal API token). Read-only: 12 tools (get_me, list_collaborations, get_project, list_project_pipelines, get_pipeline, list_pipeline_workflows, get_workflow, list_workflow_jobs, get_job, get_workflow_metrics, list_flaky_tests, list_contexts). The BYOK key travels with each request,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-circleci.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-circleci/docs"},"termsOfService":"https://connectorbay.com/byok-circleci/terms"},"servers":[{"url":"https://byok-circleci.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-circleci/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_me":{"post":{"operationId":"get_me","summary":"Show the CircleCI user the token belongs to: id, login and name. Use for \"Which CircleCI user is my token connected to\".","description":"Show the CircleCI user the token belongs to: id, login and name. Use for \"Which CircleCI user is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_meArguments","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_collaborations":{"post":{"operationId":"list_collaborations","summary":"List the organizations and accounts the CircleCI user collaborates in, with slug, name and VCS type. Use for \"Which Circ","description":"List the organizations and accounts the CircleCI user collaborates in, with slug, name and VCS type. Use for \"Which CircleCI organizations am I part of\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_collaborationsArguments","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_project":{"post":{"operationId":"get_project","summary":"Get one CircleCI project by slug: name, organization, ids and VCS information with default branch. Use for \"Show details","description":"Get one CircleCI project by slug: name, organization, ids and VCS information with default branch. Use for \"Show details of my CircleCI project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_slug":{"description":"CircleCI project slug '<vcs>/<org>/<repo>', for example 'gh/CircleCI-Public/api-preview-docs' (vcs is gh, bb or circleci; for GitHub App and GitLab projects use 'circleci/<organization id>/<project id>').","maxLength":200,"title":"Project Slug","type":"string"}},"required":["project_slug"],"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_project_pipelines":{"post":{"operationId":"list_project_pipelines","summary":"List recent pipelines of a CircleCI project (newest first) with number, state, trigger, branch, commit subject and error","description":"List recent pipelines of a CircleCI project (newest first) with number, state, trigger, branch, commit subject and errors. Page with next_page_token. Use for \"What were the latest CircleCI pipelines on my project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_slug":{"description":"CircleCI project slug '<vcs>/<org>/<repo>', for example 'gh/CircleCI-Public/api-preview-docs' (vcs is gh, bb or circleci; for GitHub App and GitLab projects use 'circleci/<organization id>/<project id>').","maxLength":200,"title":"Project Slug","type":"string"},"branch":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only pipelines for this branch.","title":"Branch"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: next_page_token from the previous answer. Leave out for the first page.","title":"Page Token"}},"required":["project_slug"],"title":"list_project_pipelinesArguments","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_pipeline":{"post":{"operationId":"get_pipeline","summary":"Get one CircleCI pipeline by id: number, state, trigger, branch, revision and commit subject. Use for \"Show this CircleC","description":"Get one CircleCI pipeline by id: number, state, trigger, branch, revision and commit subject. Use for \"Show this CircleCI pipeline\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pipeline_id":{"description":"Pipeline id (UUID), as returned by list_project_pipelines.","maxLength":60,"title":"Pipeline Id","type":"string"}},"required":["pipeline_id"],"title":"get_pipelineArguments","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_pipeline_workflows":{"post":{"operationId":"list_pipeline_workflows","summary":"List the workflows of a CircleCI pipeline with name, status, start and stop times. Page with next_page_token. Use for \"W","description":"List the workflows of a CircleCI pipeline with name, status, start and stop times. Page with next_page_token. Use for \"Which workflows ran in this CircleCI pipeline and did they pass\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"pipeline_id":{"description":"Pipeline id (UUID), as returned by list_project_pipelines.","maxLength":60,"title":"Pipeline Id","type":"string"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: next_page_token from the previous answer. Leave out for the first page.","title":"Page Token"}},"required":["pipeline_id"],"title":"list_pipeline_workflowsArguments","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_workflow":{"post":{"operationId":"get_workflow","summary":"Get one CircleCI workflow by id: name, status, pipeline, who started it, and start and stop times. Use for \"What is the ","description":"Get one CircleCI workflow by id: name, status, pipeline, who started it, and start and stop times. Use for \"What is the status of this CircleCI workflow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workflow_id":{"description":"Workflow id (UUID), as returned by list_pipeline_workflows.","maxLength":60,"title":"Workflow Id","type":"string"}},"required":["workflow_id"],"title":"get_workflowArguments","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_workflow_jobs":{"post":{"operationId":"list_workflow_jobs","summary":"List the jobs of a CircleCI workflow with name, number, type, status, dependencies and times. Page with next_page_token.","description":"List the jobs of a CircleCI workflow with name, number, type, status, dependencies and times. Page with next_page_token. Use for \"Which job failed in this CircleCI workflow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workflow_id":{"description":"Workflow id (UUID), as returned by list_pipeline_workflows.","maxLength":60,"title":"Workflow Id","type":"string"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: next_page_token from the previous answer. Leave out for the first page.","title":"Page Token"}},"required":["workflow_id"],"title":"list_workflow_jobsArguments","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_job":{"post":{"operationId":"get_job","summary":"Get one CircleCI job by id: name, number, status, workflow, pipeline and times. Use for \"Show this CircleCI job\".","description":"Get one CircleCI job by id: name, number, status, workflow, pipeline and times. Use for \"Show this CircleCI job\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"Job id (UUID), as returned by list_workflow_jobs.","maxLength":60,"title":"Job Id","type":"string"}},"required":["job_id"],"title":"get_jobArguments","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_workflow_metrics":{"post":{"operationId":"get_workflow_metrics","summary":"Get CircleCI Insights metrics per workflow of a project: runs, success rate, failed runs, credits used and duration stat","description":"Get CircleCI Insights metrics per workflow of a project: runs, success rate, failed runs, credits used and duration statistics over a reporting window. Use for \"What is the success rate of my CircleCI workflows over the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_slug":{"description":"CircleCI project slug '<vcs>/<org>/<repo>', for example 'gh/CircleCI-Public/api-preview-docs' (vcs is gh, bb or circleci; for GitHub App and GitLab projects use 'circleci/<organization id>/<project id>').","maxLength":200,"title":"Project Slug","type":"string"},"reporting_window":{"anyOf":[{"enum":["last-24-hours","last-7-days","last-30-days","last-60-days","last-90-days"],"type":"string"},{"type":"null"}],"default":null,"description":"Time window: last-24-hours, last-7-days, last-30-days, last-60-days or last-90-days.","title":"Reporting Window"},"branch":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs on this branch (default branch if omitted and all_branches is false).","title":"Branch"},"all_branches":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to aggregate across all branches.","title":"All Branches"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: next_page_token from the previous answer. Leave out for the first page.","title":"Page Token"}},"required":["project_slug"],"title":"get_workflow_metricsArguments","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_flaky_tests":{"post":{"operationId":"list_flaky_tests","summary":"List flaky tests CircleCI Insights found in a project, with test name, class, job, workflow, file and how many times it ","description":"List flaky tests CircleCI Insights found in a project, with test name, class, job, workflow, file and how many times it flaked. Use for \"Which tests are flaky in my CircleCI project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_slug":{"description":"CircleCI project slug '<vcs>/<org>/<repo>', for example 'gh/CircleCI-Public/api-preview-docs' (vcs is gh, bb or circleci; for GitHub App and GitLab projects use 'circleci/<organization id>/<project id>').","maxLength":200,"title":"Project Slug","type":"string"}},"required":["project_slug"],"title":"list_flaky_testsArguments","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_contexts":{"post":{"operationId":"list_contexts","summary":"List CircleCI contexts (shared variable groups) of an owner by name and creation date. Variable values are not returned.","description":"List CircleCI contexts (shared variable groups) of an owner by name and creation date. Variable values are not returned. Use for \"What CircleCI contexts does my organization have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"owner_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Organization id (UUID) that owns the contexts.","title":"Owner Id"},"owner_slug":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Organization slug, for example 'gh/CircleCI-Public' (use instead of owner_id).","title":"Owner Slug"},"owner_type":{"anyOf":[{"enum":["account","organization"],"type":"string"},{"type":"null"}],"default":null,"description":"Owner type: account or organization.","title":"Owner Type"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: next_page_token from the previous answer. Leave out for the first page.","title":"Page Token"}},"title":"list_contextsArguments","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}}}}