{"openapi":"3.1.0","info":{"title":"Semaphore (BYOK) API","version":"0.1.0","description":"Semaphore (BYOK) lets an AI assistant read your own Semaphore data through the Semaphore API with a key you supply (API token). Read-only: 11 tools (list_workflows, get_workflow, list_pipelines, get_pipeline, list_promotions, get_job, list_deployment_targets, list_agent_types, list_agents, list_members, list_roles). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-semaphore.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-semaphore/docs"},"termsOfService":"https://connectorbay.com/byok-semaphore/terms"},"servers":[{"url":"https://byok-semaphore.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-semaphore/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_workflows":{"post":{"operationId":"list_workflows","summary":"List the Semaphore workflows of a project (newest first, up to 30) with branch, commit, trigger and the id of the first ","description":"List the Semaphore workflows of a project (newest first, up to 30) with branch, commit, trigger and the id of the first pipeline. Use for \"What workflows ran in my Semaphore project recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"project_id":{"description":"Semaphore project id (UUID). Copy it from the project page address in Semaphore; the API has no documented project list.","maxLength":60,"title":"Project Id","type":"string"},"branch_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this branch.","title":"Branch Name"},"created_after":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items created after this Unix timestamp (seconds).","title":"Created After"},"created_before":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items created before this Unix timestamp (seconds). Use it to page back in time, since results come 30 at a time.","title":"Created Before"}},"required":["organization","project_id"],"title":"list_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 Semaphore workflow by id: branch, commit, trigger and the id of the first pipeline. Use for \"Show details of thi","description":"Get one Semaphore workflow by id: branch, commit, trigger and the id of the first pipeline. Use for \"Show details of this Semaphore workflow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"workflow_id":{"description":"Semaphore workflow id (UUID), as returned by list_workflows.","maxLength":60,"title":"Workflow Id","type":"string"}},"required":["organization","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_pipelines":{"post":{"operationId":"list_pipelines","summary":"List Semaphore pipelines of a project or workflow with name, state, result, branch and creation time. Give a project id ","description":"List Semaphore pipelines of a project or workflow with name, state, result, branch and creation time. Give a project id or a workflow id. Use for \"Did my latest Semaphore pipelines pass\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"project_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Project id (UUID). Required unless wf_id is given.","title":"Project Id"},"wf_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Workflow id (UUID). Required unless project_id is given.","title":"Wf Id"},"branch_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this branch.","title":"Branch Name"},"yml_file_path":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only pipelines defined in this YAML file.","title":"Yml File Path"},"created_after":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items created after this Unix timestamp (seconds).","title":"Created After"},"created_before":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only items created before this Unix timestamp (seconds). Use it to page back in time, since results come 30 at a time.","title":"Created Before"},"done_after":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only pipelines finished after this Unix timestamp (seconds).","title":"Done After"},"done_before":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only pipelines finished before this Unix timestamp (seconds).","title":"Done Before"}},"required":["organization"],"title":"list_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 Semaphore pipeline by id: state, result, branch, commit message and queue, run and finish times. Environment var","description":"Get one Semaphore pipeline by id: state, result, branch, commit message and queue, run and finish times. Environment variables are not returned. Use for \"What is the status of this Semaphore pipeline\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"pipeline_id":{"description":"Semaphore pipeline id (UUID), for example the initial_ppl_id of a workflow.","maxLength":60,"title":"Pipeline Id","type":"string"}},"required":["organization","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_promotions":{"post":{"operationId":"list_promotions","summary":"List the promotions (deployment pipelines) of a Semaphore pipeline with name, status and what triggered them. Use for \"W","description":"List the promotions (deployment pipelines) of a Semaphore pipeline with name, status and what triggered them. Use for \"Which promotions ran for this Semaphore pipeline\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"pipeline_id":{"description":"Semaphore pipeline id (UUID).","maxLength":60,"title":"Pipeline Id","type":"string"}},"required":["organization","pipeline_id"],"title":"list_promotionsArguments","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 Semaphore job by id: name, state, result and create, start and finish times. Use for \"How did this Semaphore job","description":"Get one Semaphore job by id: name, state, result and create, start and finish times. Use for \"How did this Semaphore job end\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"job_id":{"description":"Semaphore job id (UUID).","maxLength":60,"title":"Job Id","type":"string"}},"required":["organization","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/list_deployment_targets":{"post":{"operationId":"list_deployment_targets","summary":"List the deployment targets of a Semaphore project with name, state, active flag and last update. Use for \"What deployme","description":"List the deployment targets of a Semaphore project with name, state, active flag and last update. Use for \"What deployment targets does my Semaphore project have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"project_id":{"description":"Semaphore project id (UUID). Copy it from the project page address in Semaphore; the API has no documented project list.","maxLength":60,"title":"Project Id","type":"string"}},"required":["organization","project_id"],"title":"list_deployment_targetsArguments","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_agent_types":{"post":{"operationId":"list_agent_types","summary":"List the self-hosted agent types of the organization with name, agent count and timestamps. Registration tokens are not ","description":"List the self-hosted agent types of the organization with name, agent count and timestamps. Registration tokens are not returned. Use for \"Which self-hosted agent types do I have on Semaphore\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"}},"required":["organization"],"title":"list_agent_typesArguments","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_agents":{"post":{"operationId":"list_agents","summary":"List connected self-hosted agents with state, type, version, OS, hostname and connection time. IP addresses are not retu","description":"List connected self-hosted agents with state, type, version, OS, hostname and connection time. IP addresses are not returned. Use for \"Which self-hosted agents are connected to Semaphore\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"agent_type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only agents of this agent type name.","title":"Agent Type"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":200,"description":"Agents per page (1 to 200, default 200).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: the 'cursor' value of the previous answer. Leave out for the first page.","title":"Cursor"}},"required":["organization"],"title":"list_agentsArguments","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 the members of the Semaphore organization with id, name and type. Roles are not expanded. Without member_type only ","description":"List the members of the Semaphore organization with id, name and type. Roles are not expanded. Without member_type only human users are listed. Use for \"Who is in my Semaphore organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"},"member_type":{"anyOf":[{"enum":["user","service_account","group"],"type":"string"},{"type":"null"}],"default":null,"description":"Kind of member to list.","title":"Member Type"},"page_no":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page No"},"page_size":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":500,"description":"Members per page (1 to 500, default 500).","title":"Page Size"}},"required":["organization"],"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_roles":{"post":{"operationId":"list_roles","summary":"List the roles defined in the Semaphore organization with name, scope, description and permission names. Use for \"What r","description":"List the roles defined in the Semaphore organization with name, scope, description and permission names. Use for \"What roles exist in my Semaphore organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"organization":{"description":"Your Semaphore organization handle, the first part of your address: 'acme' for acme.semaphoreci.com. Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Organization","type":"string"}},"required":["organization"],"title":"list_rolesArguments","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}}}}