{"openapi":"3.1.0","info":{"title":"GitLab Runners (BYOK) API","version":"0.1.0","description":"GitLab Runners (BYOK) lets an AI assistant read your own GitLab Runners data through the GitLab Runners API with a key you supply (personal access token (read_api scope)). Read-only: 6 tools (list_runners, get_runner, list_runner_jobs, list_runner_managers, list_project_runners, list_group_runners). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-gitlab-runners.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-gitlab-runners/docs"},"termsOfService":"https://connectorbay.com/byok-gitlab-runners/terms"},"servers":[{"url":"https://byok-gitlab-runners.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-gitlab-runners/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_runners":{"post":{"operationId":"list_runners","summary":"List the CI runners you can see (group and project runners you own or maintain, plus instance runners) with type, status","description":"List the CI runners you can see (group and project runners you own or maintain, plus instance runners) with type, status and whether they are paused. Use for \"Which of my GitLab CI runners are offline\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"enum":["instance_type","group_type","project_type"],"type":"string"},{"type":"null"}],"default":null,"description":"Only runners of this type.","title":"Type"},"status":{"anyOf":[{"enum":["online","offline","stale","never_contacted"],"type":"string"},{"type":"null"}],"default":null,"description":"Only runners in this status (offline can include stale).","title":"Status"},"paused":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only runners that ignore new jobs, false for only runners that accept them.","title":"Paused"},"tag_list":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated runner tags to require, for example 'docker,linux'.","title":"Tag List"},"version_prefix":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only runners whose version starts with this text, for example '17.' or '17.4.1'.","title":"Version Prefix"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (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_runnersArguments","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_runner":{"post":{"operationId":"get_runner","summary":"Get one runner: description, type, status, last contact time, tags, access level, maximum job timeout and the projects i","description":"Get one runner: description, type, status, last contact time, tags, access level, maximum job timeout and the projects it serves. Use for \"Show details of GitLab runner 6\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"runner_id":{"description":"Numeric ID of the runner (from list_runners).","title":"Runner Id","type":"integer"}},"required":["runner_id"],"title":"get_runnerArguments","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_runner_jobs":{"post":{"operationId":"list_runner_jobs","summary":"List jobs a runner is running or has run, limited to projects where you have at least Reporter access, with status, ref,","description":"List jobs a runner is running or has run, limited to projects where you have at least Reporter access, with status, ref, timing and project. Use for \"What jobs has GitLab runner 6 processed lately\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"runner_id":{"description":"Numeric ID of the runner (from list_runners).","title":"Runner Id","type":"integer"},"status":{"anyOf":[{"enum":["created","waiting_for_resource","preparing","pending","running","success","failed","canceled","skipped","manual","scheduled"],"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs with this status.","title":"Status"},"system_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs run by the runner manager with this system ID.","title":"System Id"},"order_by":{"anyOf":[{"const":"id","type":"string"},{"type":"null"}],"default":null,"description":"Sort field (only id is supported).","title":"Order By"},"sort":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction; requires order_by.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (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"}},"required":["runner_id"],"title":"list_runner_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/list_runner_managers":{"post":{"operationId":"list_runner_managers","summary":"List the runner managers (machines) of one runner with version, platform, architecture, last contact and job execution s","description":"List the runner managers (machines) of one runner with version, platform, architecture, last contact and job execution status. Use for \"Which machines run GitLab runner 6 and which version\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"runner_id":{"description":"Numeric ID of the runner (from list_runners).","title":"Runner Id","type":"integer"}},"required":["runner_id"],"title":"list_runner_managersArguments","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_runners":{"post":{"operationId":"list_project_runners","summary":"List runners available to a project, including group runners and enabled instance runners (needs Maintainer or Auditor a","description":"List runners available to a project, including group runners and enabled instance runners (needs Maintainer or Auditor access). Use for \"Which CI runners can gitlab-org/gitlab use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project":{"description":"Numeric project ID, or the full path with namespace such as 'gitlab-org/gitlab' (slashes are encoded for you).","maxLength":200,"title":"Project","type":"string"},"type":{"anyOf":[{"enum":["instance_type","group_type","project_type"],"type":"string"},{"type":"null"}],"default":null,"description":"Only runners of this type.","title":"Type"},"status":{"anyOf":[{"enum":["online","offline","stale","never_contacted"],"type":"string"},{"type":"null"}],"default":null,"description":"Only runners in this status (offline can include stale).","title":"Status"},"paused":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only runners that ignore new jobs, false for only runners that accept them.","title":"Paused"},"tag_list":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated runner tags to require, for example 'docker,linux'.","title":"Tag List"},"version_prefix":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only runners whose version starts with this text, for example '17.' or '17.4.1'.","title":"Version Prefix"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (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"}},"required":["project"],"title":"list_project_runnersArguments","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_group_runners":{"post":{"operationId":"list_group_runners","summary":"List runners available to a group, including ancestor group runners and enabled instance runners (needs Owner or Auditor","description":"List runners available to a group, including ancestor group runners and enabled instance runners (needs Owner or Auditor access). Use for \"Which CI runners does the gitlab-org group have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group":{"description":"Numeric group ID, or the full group path such as 'gitlab-org' (slashes are encoded for you).","maxLength":200,"title":"Group","type":"string"},"type":{"anyOf":[{"enum":["instance_type","group_type","project_type"],"type":"string"},{"type":"null"}],"default":null,"description":"Only runners of this type.","title":"Type"},"status":{"anyOf":[{"enum":["online","offline","stale","never_contacted"],"type":"string"},{"type":"null"}],"default":null,"description":"Only runners in this status (offline can include stale).","title":"Status"},"paused":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only runners that ignore new jobs, false for only runners that accept them.","title":"Paused"},"tag_list":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated runner tags to require, for example 'docker,linux'.","title":"Tag List"},"version_prefix":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only runners whose version starts with this text, for example '17.' or '17.4.1'.","title":"Version Prefix"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (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"}},"required":["group"],"title":"list_group_runnersArguments","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}}}}