{ "openapi": "3.1.0", "info": { "title": "CIHub API", "description": "The API of a CIHub instance: read the queues, the PRs in them and their runs; submit, cancel and restart a PR; pause, drain and resume a queue. The dashboard and the `cihub` command line use it too. The API is at `/api/v1` on the address of the instance, next to the dashboard.\n\n## Authentication\n\nSend an API token of the organization in the header `Authorization: Bearer `. `cihub-server token create --org ` creates the first one. A token has scopes:\n\n| Scope | Allows |\n| -------------- | ---------------------------------------------------------- |\n| `queues:read` | Read the queues, their PRs and their runs |\n| `queues:write` | Pause, drain, resume and read again a queue; read the audit log |\n| `prs:write` | Submit, cancel and restart a PR |\n\nThe dashboard uses the session of a person instead: the cookie `__Host-cihub_session`. The role of the person in the organization of the URL gives the scopes: `admin` has every scope, `member` has `queues:read` and `prs:write`. A request of a session that can change a state (any method but `GET`, `HEAD` and `OPTIONS`) also sends the header `X-CSRF-Token`, with the value of the cookie `__Host-cihub_csrf`.\n\nThe `cihub` command line acts as a person too: `cihub auth login` asks `POST /device-codes` for a code, the person approves it on the page `/device` of the dashboard, and `POST /device-codes/token` then gives a session of the command line, `chc_…`, which goes in `Authorization: Bearer` as a token, with the scopes of the role of the person and no CSRF token.\n\n## Names in the URL\n\nA route names the organization by its slug, then the repository by its name and the queue by its target branch, percent-encoded: `/orgs/acme/repos/web/queues/main`, `/orgs/acme/repos/web/queues/release%2F2.0`. A PR belongs to its repository: `/orgs/acme/repos/web/prs/118`; its base branch gives its queue. The case of the slug and of the repository does not matter. An organization that the token or the person does not belong to answers `404 org_not_found`, as one that does not exist.\n\n## Requests that the queue does later\n\nA submission, a cancellation, a restart, a change of the state of a queue and a new read of a queue answer `202 Accepted`, without a body: the queue applies them at its next reconciliation, within seconds. `GET /orgs/{org}/stream` tells when a queue changed.\n\n## Pages\n\nA list gives a page. `limit` asks for 1 to 100 entries (50 by default), and `from` takes the `cursor` of the previous page. The answer names its entries after the resource (`prs`, `queues`, …) and adds:\n\n| Field | Meaning |\n| ---------- | -------------------------------------------------------------------- |\n| `has_more` | More entries follow this page |\n| `count` | How many entries the list has, every page together |\n| `cursor` | The `from` of the next page; `null` on the last page. It is opaque: pass it back as it is |\n\nA cursor of another list, or one that does not read, answers `400 invalid_cursor`.\n\n## Rate limits\n\nA token or a session makes at most 600 requests per minute on each replica of the server; past it, the answer is `429 rate_limited` with the header `Retry-After`. The two routes of the sign-in of the command line that need no token allow 120 requests per minute for each client address. A token or a person keeps at most 8 streams open.\n\n## Errors\n\nAn error is a `application/problem+json` document (RFC 9457). Decide on its `code`, never on `detail`, whose text can change:\n\n```json\n{\n \"type\": \"https://cihub.io/docs/api/errors#queue_not_found\",\n \"title\": \"Not Found\",\n \"status\": 404,\n \"detail\": \"no queue of `main`\",\n \"code\": \"queue_not_found\"\n}\n```\n\nIts `type` is the page of the documentation that explains its `code`. Each route lists the codes that it can answer. Every code:\n\n| Code | Status | Meaning |\n| --- | --- | --- |\n| `invalid_request` | 400 | The body, the path or the query of the request is not valid. |\n| `limit_out_of_range` | 400 | `limit` is from 1 to 100. |\n| `invalid_cursor` | 400 | `from` is not a `cursor` that this list gave. |\n| `unknown_priority` | 400 | The name of the priority is not `urgent`, `high`, `medium` or `low`. |\n| `device_code_pending` | 400 | The person has not approved or denied the code yet: ask again after `interval` seconds. |\n| `device_code_expired` | 400 | The device code is unknown, already used, or older than 15 minutes: start again. |\n| `unauthorized` | 401 | No API token or session, or one that is unknown or expired. |\n| `scope_missing` | 403 | The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route. |\n| `csrf_refused` | 403 | A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`. |\n| `device_code_denied` | 403 | The person denied the code: the command line is not signed in. |\n| `route_not_found` | 404 | No route has this path. |\n| `org_not_found` | 404 | No organization has this slug, or the token or the user does not belong to it. |\n| `repo_not_found` | 404 | The organization has no repository with this name. |\n| `queue_not_found` | 404 | The repository has no queue of this branch. |\n| `pr_not_found` | 404 | The PR was never submitted to a queue of the repository. |\n| `run_not_found` | 404 | The organization has no run with this identifier. |\n| `device_code_not_found` | 404 | No sign-in of the command line waits for this code: it is wrong, used, or older than 15 minutes. |\n| `pr_already_queued` | 409 | The PR is already in a queue of the repository, and its item has not ended. |\n| `item_ended` | 409 | The item of the PR ended: `merged`, `failed` or `cancelled`. |\n| `item_not_in_test` | 409 | Only an item in `testing` or `pending_failure` can restart its tests. |\n| `rate_limited` | 429 | The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds. |\n| `too_many_streams` | 429 | The token or the person already keeps 8 streams open. |\n| `polling_too_fast` | 429 | The command line asked again sooner than `interval`: wait 5 seconds more each time. |\n| `internal` | 500 | The server failed; the logs of the instance say why. |\n| `sign_in_unavailable` | 503 | The instance has no public address or no sign-in client: nobody signs in to it. |\n| `scm_unavailable` | 503 | The SCM did not answer the check of the access of the person of the session: try again in a moment. |\n", "license": { "name": "FSL-1.1-ALv2", "identifier": "FSL-1.1-ALv2" }, "version": "1" }, "servers": [ { "url": "{base_url}/api/v1", "description": "Another instance", "variables": { "base_url": { "default": "https://cihub.example.com", "description": "The address of the instance" } } } ], "paths": { "/device-codes": { "post": { "tags": [ "Session" ], "summary": "Start a sign-in of the command line", "description": "A device code, for the command line, and its user code, for the person,\nwho approves it on the page `verification_url`. The command line then\nasks `POST /device-codes/token` every `interval` seconds.\n\n**Access**: no token or session.", "operationId": "start_device_sign_in", "responses": { "200": { "description": "A sign-in that waits for its person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCode" } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `sign_in_unavailable`: The instance has no public address or no sign-in client: nobody signs in to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "sign_in_unavailable": { "$ref": "#/components/examples/sign_in_unavailable" } } } } } } } }, "/device-codes/token": { "post": { "tags": [ "Session" ], "summary": "Get the session of the command line", "description": "The session, once the person approved the code; it is given once, and\nthe code is used. Before, the answer says to ask again after `interval`\nseconds, 5 seconds more after each `polling_too_fast`.\n\n**Access**: no token or session.", "operationId": "get_device_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCodeToken" } } }, "required": true }, "responses": { "200": { "description": "The session of the command line.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliSession" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `device_code_pending`: The person has not approved or denied the code yet: ask again after `interval` seconds.\n- `device_code_expired`: The device code is unknown, already used, or older than 15 minutes: start again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_code_expired": { "$ref": "#/components/examples/device_code_expired" }, "device_code_pending": { "$ref": "#/components/examples/device_code_pending" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" } } } } }, "403": { "description": "- `device_code_denied`: The person denied the code: the command line is not signed in.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_code_denied": { "$ref": "#/components/examples/device_code_denied" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.\n- `polling_too_fast`: The command line asked again sooner than `interval`: wait 5 seconds more each time.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "polling_too_fast": { "$ref": "#/components/examples/polling_too_fast" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } } } } }, "/device-codes/{user_code}/approve": { "post": { "tags": [ "Session" ], "summary": "Approve a sign-in of the command line", "description": "The person of the session approves the code that their command line\nshows: the command line then signs in as them.\n\n**Access**: the session of a person: the dashboard, or the command line.", "operationId": "approve_device_code", "parameters": [ { "name": "user_code", "in": "path", "description": "The code that the command line shows.", "required": true, "schema": { "type": "string" }, "example": "WDJB-MJHT" } ], "responses": { "204": { "description": "The command line signs in as the person." }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" } } } } }, "404": { "description": "- `device_code_not_found`: No sign-in of the command line waits for this code: it is wrong, used, or older than 15 minutes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_code_not_found": { "$ref": "#/components/examples/device_code_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } } }, "security": [ { "session": [] } ] } }, "/device-codes/{user_code}/deny": { "post": { "tags": [ "Session" ], "summary": "Deny a sign-in of the command line", "description": "The person of the session denies a code that they did not ask for: no\ncommand line signs in with it.\n\n**Access**: the session of a person: the dashboard, or the command line.", "operationId": "deny_device_code", "parameters": [ { "name": "user_code", "in": "path", "description": "The code that the command line shows.", "required": true, "schema": { "type": "string" }, "example": "WDJB-MJHT" } ], "responses": { "204": { "description": "No command line signs in with the code." }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" } } } } }, "404": { "description": "- `device_code_not_found`: No sign-in of the command line waits for this code: it is wrong, used, or older than 15 minutes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "device_code_not_found": { "$ref": "#/components/examples/device_code_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } } }, "security": [ { "session": [] } ] } }, "/instance": { "get": { "tags": [ "Session" ], "summary": "Get the instance", "description": "The version of the instance, and the page of the SCM that installs the\nApp.\n\n**Access**: any API token or session.", "operationId": "get_instance", "responses": { "200": { "description": "The instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Instance" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } } }, "security": [ { "token": [] }, { "session": [] } ] } }, "/orgs/{org}": { "get": { "tags": [ "Organizations" ], "summary": "Get an organization", "description": "The organization, and the role of the person of the session in it.\n\n**Access**: any API token or session.", "operationId": "get_org", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" } ], "responses": { "200": { "description": "The organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Org" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "404": { "description": "- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [] }, { "session": [] } ] } }, "/orgs/{org}/audit": { "get": { "tags": [ "Organizations" ], "summary": "List the audit log", "description": "The changes of the queues and the actions on the PRs that a person or a\ntoken asked for, newest first.\n\n**Scope**: `queues:write`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "list_audit", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "from", "in": "query", "description": "The `cursor` of the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many entries, from 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of the audit log.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditList" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `limit_out_of_range`: `limit` is from 1 to 100.\n- `invalid_cursor`: `from` is not a `cursor` that this list gave.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "limit_out_of_range": { "$ref": "#/components/examples/limit_out_of_range" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:write" ] }, { "session": [] } ] } }, "/orgs/{org}/prs": { "get": { "tags": [ "Pull requests" ], "summary": "List the PRs of the organization", "description": "The PRs in the queues of every repository of the organization: the\ncurrent submission of each PR in each queue, with the PRs that merge before\nit and an estimate. Without a filter, every PR, live or ended.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "list_org_prs", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "author", "in": "query", "description": "Only the PRs of this author, whatever the case of the login.", "required": false, "schema": { "type": "string" }, "example": "octocat" }, { "name": "state", "in": "query", "description": "Only the PRs in these states, separated by commas: `not_ready`,\n`pending`, `testing`, `tests_passed`, `pending_failure`, `merged`,\n`failed`, `cancelled`.", "required": false, "schema": { "type": "string" }, "example": "pending,testing" }, { "name": "submitted_since", "in": "query", "description": "Submitted at or after this time (RFC 3339).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "submitted_until", "in": "query", "description": "Submitted before this time (RFC 3339).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "state_changed_since", "in": "query", "description": "Reached their state at or after this time (RFC 3339).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "description": "`newest` (by default) or `position`.", "required": false, "schema": { "type": "string", "description": "The order of a list of PRs.", "enum": [ "newest", "position" ] } }, { "name": "from", "in": "query", "description": "The `cursor` of the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many PRs, from 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of PRs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrList" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `limit_out_of_range`: `limit` is from 1 to 100.\n- `invalid_cursor`: `from` is not a `cursor` that this list gave.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "limit_out_of_range": { "$ref": "#/components/examples/limit_out_of_range" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/queues": { "get": { "tags": [ "Queues" ], "summary": "List the queues of the organization", "description": "Every queue of the organization, with its counters and its settings, by\nrepository name then target branch: the overview of the dashboard.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "list_org_queues", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "q", "in": "query", "description": "Only the queues of the repositories whose name holds this text,\nwhatever its case; from 1 to 100 characters.", "required": false, "schema": { "type": "string" }, "example": "web" }, { "name": "from", "in": "query", "description": "The `cursor` of the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many queues, from 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of queues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueList" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `limit_out_of_range`: `limit` is from 1 to 100.\n- `invalid_cursor`: `from` is not a `cursor` that this list gave.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "limit_out_of_range": { "$ref": "#/components/examples/limit_out_of_range" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos": { "get": { "tags": [ "Repositories" ], "summary": "List the repositories", "description": "The repositories of the organization that the App reaches, by owner then\nname, each with what the caller may do on it and the verdict of its\nsetup. Reads Postgres only.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "list_repos", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "state", "in": "query", "description": "Only the repositories whose setup is in these states, separated by\ncommas: `started`, `checking`, `ready`, `ready_with_warnings`,\n`cannot_merge`, `invalid_config`.", "required": false, "schema": { "type": "string" }, "example": "checking,ready,cannot_merge" }, { "name": "q", "in": "query", "description": "Only the repositories whose name holds this text, whatever its case;\nfrom 1 to 100 characters.", "required": false, "schema": { "type": "string" }, "example": "web" }, { "name": "from", "in": "query", "description": "The `cursor` of the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many repositories, from 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of repositories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoList" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `limit_out_of_range`: `limit` is from 1 to 100.\n- `invalid_cursor`: `from` is not a `cursor` that this list gave.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "limit_out_of_range": { "$ref": "#/components/examples/limit_out_of_range" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}": { "get": { "tags": [ "Repositories" ], "summary": "Get a repository", "description": "The repository, whatever the case of its name, with what the caller may\ndo on it and its whole setup. Reads Postgres only.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "get_repo", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" } ], "responses": { "200": { "description": "The repository.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoDetail" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/prs": { "get": { "tags": [ "Pull requests" ], "summary": "List the PRs of a repository", "description": "The PRs in the queues of the repository, or of one of its queues: the\ncurrent submission of each PR in each queue, with the PRs that merge\nbefore it and an estimate. Without a filter, every PR, live or ended.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "list_repo_prs", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "queue", "in": "query", "description": "Only the PRs of the queue of this target branch.", "required": false, "schema": { "type": "string" }, "example": "main" }, { "name": "author", "in": "query", "description": "Only the PRs of this author, whatever the case of the login.", "required": false, "schema": { "type": "string" }, "example": "octocat" }, { "name": "state", "in": "query", "description": "Only the PRs in these states, separated by commas: `not_ready`,\n`pending`, `testing`, `tests_passed`, `pending_failure`, `merged`,\n`failed`, `cancelled`.", "required": false, "schema": { "type": "string" }, "example": "pending,testing" }, { "name": "submitted_since", "in": "query", "description": "Submitted at or after this time (RFC 3339).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "submitted_until", "in": "query", "description": "Submitted before this time (RFC 3339).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "state_changed_since", "in": "query", "description": "Reached their state at or after this time (RFC 3339).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "description": "`newest` (by default) or `position`.", "required": false, "schema": { "type": "string", "description": "The order of a list of PRs.", "enum": [ "newest", "position" ] } }, { "name": "from", "in": "query", "description": "The `cursor` of the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many PRs, from 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of PRs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrList" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `limit_out_of_range`: `limit` is from 1 to 100.\n- `invalid_cursor`: `from` is not a `cursor` that this list gave.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "limit_out_of_range": { "$ref": "#/components/examples/limit_out_of_range" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `queue_not_found`: The repository has no queue of this branch.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "queue_not_found": { "$ref": "#/components/examples/queue_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/prs/{number}": { "get": { "tags": [ "Pull requests" ], "summary": "Get a PR", "description": "The last submission of the PR to a queue of the repository, with the PRs\nthat merge before it and an estimate.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "get_pr", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "number", "in": "path", "description": "The number of the PR in the repository.", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 118 } ], "responses": { "200": { "description": "The PR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pr" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "$ref": "#/components/examples/invalid_request" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `pr_not_found`: The PR was never submitted to a queue of the repository.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "pr_not_found": { "$ref": "#/components/examples/pr_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/prs/{number}/cancel": { "post": { "tags": [ "Pull requests" ], "summary": "Cancel a PR", "description": "Takes the PR out of its queue: its current submission ends `cancelled`\n(`admin_requested`), and stays readable.\n\n**Scope**: `prs:write`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "cancel", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "number", "in": "path", "description": "The number of the PR in the repository.", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 118 } ], "responses": { "202": { "description": "The queue takes the request." }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "$ref": "#/components/examples/invalid_request" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.\n- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" }, "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `pr_not_found`: The PR was never submitted to a queue of the repository.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "pr_not_found": { "$ref": "#/components/examples/pr_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "409": { "description": "- `item_ended`: The item of the PR ended: `merged`, `failed` or `cancelled`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "item_ended": { "$ref": "#/components/examples/item_ended" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "prs:write" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/prs/{number}/events": { "get": { "tags": [ "Pull requests" ], "summary": "List the events of a PR", "description": "The history of the PR in the queues of the repository, every submission\ntogether, oldest first.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "list_events", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "number", "in": "path", "description": "The number of the PR in the repository.", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 118 }, { "name": "from", "in": "query", "description": "The `cursor` of the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many events, from 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `limit_out_of_range`: `limit` is from 1 to 100.\n- `invalid_cursor`: `from` is not a `cursor` that this list gave.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "limit_out_of_range": { "$ref": "#/components/examples/limit_out_of_range" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `pr_not_found`: The PR was never submitted to a queue of the repository.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "pr_not_found": { "$ref": "#/components/examples/pr_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/prs/{number}/restart": { "post": { "tags": [ "Pull requests" ], "summary": "Restart the tests of a PR", "description": "Tests again the current submission of the PR, in `testing` or\n`pending_failure` (`tests_restarted_by_api_request`).\n\n**Scope**: `prs:write`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "restart", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "number", "in": "path", "description": "The number of the PR in the repository.", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 118 } ], "responses": { "202": { "description": "The queue takes the request." }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "$ref": "#/components/examples/invalid_request" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.\n- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" }, "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `pr_not_found`: The PR was never submitted to a queue of the repository.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "pr_not_found": { "$ref": "#/components/examples/pr_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "409": { "description": "- `item_not_in_test`: Only an item in `testing` or `pending_failure` can restart its tests.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "item_not_in_test": { "$ref": "#/components/examples/item_not_in_test" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "prs:write" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/prs/{number}/submit": { "post": { "tags": [ "Pull requests" ], "summary": "Submit a PR", "description": "The queue of the base branch of the PR takes it at its next\nreconciliation. A PR already in a queue answers `409` at once; the\nrefusals that need a read of the SCM, such as a queue that accepts\nnothing, come later, on the PR.\n\n**Scope**: `prs:write`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "submit", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "number", "in": "path", "description": "The number of the PR in the repository.", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 118 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitPr" } } }, "required": true }, "responses": { "202": { "description": "The queue takes the request." }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `unknown_priority`: The name of the priority is not `urgent`, `high`, `medium` or `low`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "unknown_priority": { "$ref": "#/components/examples/unknown_priority" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.\n- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" }, "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "409": { "description": "- `pr_already_queued`: The PR is already in a queue of the repository, and its item has not ended.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "pr_already_queued": { "$ref": "#/components/examples/pr_already_queued" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "prs:write" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/queues": { "get": { "tags": [ "Queues" ], "summary": "List the queues of a repository", "description": "The queues of the repository with their counters and their settings, by\ntarget branch. The first `/cihub merge` on a PR of a branch creates its queue.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "list_repo_queues", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "from", "in": "query", "description": "The `cursor` of the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many queues, from 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of queues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueList" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `limit_out_of_range`: `limit` is from 1 to 100.\n- `invalid_cursor`: `from` is not a `cursor` that this list gave.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "limit_out_of_range": { "$ref": "#/components/examples/limit_out_of_range" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/queues/{queue}": { "get": { "tags": [ "Queues" ], "summary": "Get a queue", "description": "The queue with its counters, its window, its settings and the last check\nof its configuration: the page of the queue in the dashboard.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "get_queue", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "queue", "in": "path", "description": "The target branch of the queue, percent-encoded: `release%2F2.0`.", "required": true, "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "The queue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Queue" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `queue_not_found`: The repository has no queue of this branch.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "queue_not_found": { "$ref": "#/components/examples/queue_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] }, "patch": { "tags": [ "Queues" ], "summary": "Change the state of a queue", "description": "Asks the queue for `running`, `paused` or `draining`; the queue changes\nat its next reconciliation. A queue that lost its access takes the state\nand stays stopped until the access comes back.\n\n**Scope**: `queues:write`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "update_queue", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "queue", "in": "path", "description": "The target branch of the queue, percent-encoded: `release%2F2.0`.", "required": true, "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQueue" } } }, "required": true }, "responses": { "202": { "description": "The queue takes the request." }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "$ref": "#/components/examples/invalid_request" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.\n- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" }, "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `queue_not_found`: The repository has no queue of this branch.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "queue_not_found": { "$ref": "#/components/examples/queue_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:write" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/queues/{queue}/graph": { "get": { "tags": [ "Queues" ], "summary": "Get the merge graph", "description": "The head of the target branch, the live items in order, the predecessors\nthat the test of each one merges before it, and the last run of each live\ngroup.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "graph", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "queue", "in": "path", "description": "The target branch of the queue, percent-encoded: `release%2F2.0`.", "required": true, "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "The merge graph.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Graph" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `queue_not_found`: The repository has no queue of this branch.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "queue_not_found": { "$ref": "#/components/examples/queue_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/queues/{queue}/health": { "get": { "tags": [ "Queues" ], "summary": "Get the Health of a queue", "description": "What the queue did over the period: the PRs that merged and failed, their\ntime to merge, why the others left, and the checks of its runs, each\nagainst the period before: the last 24 hours, 7 days or 30 days, or the\nhours between two times. Read from the hourly aggregate of the facts of the\nlog, which arrive a few seconds after the log; the medians and the 90th\npercentiles are within 5 %.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "get_health", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "queue", "in": "path", "description": "The target branch of the queue, percent-encoded: `release%2F2.0`.", "required": true, "schema": { "type": "string" }, "example": "main" }, { "name": "range", "in": "query", "description": "`24h` (by default), `7d` or `30d`; not with `from` and `to`.", "required": false, "schema": { "type": "string", "description": "The period of the Health of a queue.", "enum": [ "24h", "7d", "30d" ] } }, { "name": "from", "in": "query", "description": "The start of a period instead of `range`, with `to` (RFC 3339): from\nits UTC hour, in the last 13 months.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "The end of the period, with `from` (RFC 3339): to the end of its UTC\nhour, or of the current hour. Its buckets are hours up to 2 days, UTC\ndays up to 90 days, and weeks from a Monday beyond.", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "The Health of the queue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueHealth" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `queue_not_found`: The repository has no queue of this branch.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "queue_not_found": { "$ref": "#/components/examples/queue_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/queues/{queue}/sync": { "post": { "tags": [ "Queues" ], "summary": "Sync a queue", "description": "Reads again from the SCM each live PR, the checks of each live run, the\nhead of the target branch and its configuration: the way out after an\nincident.\n\n**Scope**: `queues:write`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "sync_queue", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "queue", "in": "path", "description": "The target branch of the queue, percent-encoded: `release%2F2.0`.", "required": true, "schema": { "type": "string" }, "example": "main" } ], "responses": { "202": { "description": "The queue takes the request." }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.\n- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" }, "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `queue_not_found`: The repository has no queue of this branch.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "queue_not_found": { "$ref": "#/components/examples/queue_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:write" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/runs/{run_id}": { "get": { "tags": [ "Runs" ], "summary": "Get a run", "description": "The run, its test branch, the PRs that it tests and their predecessors,\nevery check observed on it, and the live runs that depend on it. A job of\nthe CI reads its run identifier in the last segment of its branch; a run of\nanother repository answers `run_not_found`.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "get_run", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" }, { "name": "run_id", "in": "path", "description": "The identifier of the run.", "required": true, "schema": { "type": "string" }, "example": "run_06cx8fn2wtgkyc9x5csgnm5r22ca6g0w" } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `run_not_found`: The organization has no run with this identifier.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" }, "run_not_found": { "$ref": "#/components/examples/run_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/orgs/{org}/repos/{repo}/sync": { "post": { "tags": [ "Repositories" ], "summary": "Sync the setup of a repository", "description": "Asks CIHub to read the setup of the repository from the SCM now, at most\nonce a minute; its `requested_at` shows the read until it ends.\n\n**Scope**: `queues:write`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "sync_repo", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" }, { "name": "repo", "in": "path", "description": "The name of the repository in the organization.", "required": true, "schema": { "type": "string" }, "example": "web" } ], "responses": { "202": { "description": "CIHub takes the request." }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.\n- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" }, "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `repo_not_found`: The organization has no repository with this name.\n- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" }, "repo_not_found": { "$ref": "#/components/examples/repo_not_found" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:write" ] }, { "session": [] } ] } }, "/orgs/{org}/stream": { "get": { "tags": [ "Live updates" ], "summary": "Follow the queues", "description": "The changes of the queues of the organization, as server-sent events: an\nevent `queue_changed` each time what the pages of a queue show changes,\nwhose data is a `QueueChanged`, and a comment `: ping` every 15 seconds.\nThe stream ends after 5 minutes, when the server stops, and when it lost\nchanges: open it again after `retry` milliseconds, and read the queues\nagain.\n\n**Scope**: `queues:read`, for an API token, or for the role of the user of a session or their permission on the repository of the route.", "operationId": "stream", "parameters": [ { "name": "org", "in": "path", "description": "The slug of the organization.", "required": true, "schema": { "type": "string" }, "example": "acme" } ], "responses": { "200": { "description": "The stream of the changes.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/QueueChanged" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `scope_missing`: The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scope_missing": { "$ref": "#/components/examples/scope_missing" } } } } }, "404": { "description": "- `org_not_found`: No organization has this slug, or the token or the user does not belong to it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "org_not_found": { "$ref": "#/components/examples/org_not_found" } } } } }, "429": { "description": "- `too_many_streams`: The token or the person already keeps 8 streams open.\n- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "too_many_streams": { "$ref": "#/components/examples/too_many_streams" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } }, "503": { "description": "- `scm_unavailable`: The SCM did not answer the check of the access of the person of the session: try again in a moment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "scm_unavailable": { "$ref": "#/components/examples/scm_unavailable" } } } } } }, "security": [ { "token": [ "queues:read" ] }, { "session": [] } ] } }, "/user": { "get": { "tags": [ "Session" ], "summary": "Get the user", "description": "The person of the session of the dashboard. An API token stands for no\nperson: it gets `401`.\n\n**Access**: the session of a person: the dashboard, or the command line.", "operationId": "get_user", "responses": { "200": { "description": "The person of the session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } } }, "security": [ { "session": [] } ] } }, "/user/orgs": { "get": { "tags": [ "Session" ], "summary": "List the organizations of the user", "description": "The organizations where the person of the session has a role, by slug;\nnone before the App is installed on an account of the person.\n\n**Access**: the session of a person: the dashboard, or the command line.", "operationId": "list_user_orgs", "parameters": [ { "name": "from", "in": "query", "description": "The `cursor` of the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "How many entries, from 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of organizations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgList" } } } }, "400": { "description": "- `invalid_request`: The body, the path or the query of the request is not valid.\n- `limit_out_of_range`: `limit` is from 1 to 100.\n- `invalid_cursor`: `from` is not a `cursor` that this list gave.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_request": { "$ref": "#/components/examples/invalid_request" }, "limit_out_of_range": { "$ref": "#/components/examples/limit_out_of_range" } } } } }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } } }, "security": [ { "session": [] } ] } }, "/user/session": { "delete": { "tags": [ "Session" ], "summary": "End the session", "description": "Ends the session of the request: the sign-out of the command line. The\ndashboard signs out with `POST /auth/sign-out`, which also clears its\ncookies.\n\n**Access**: the session of a person: the dashboard, or the command line.", "operationId": "delete_user_session", "responses": { "204": { "description": "The session ended." }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } } }, "security": [ { "session": [] } ] } }, "/user/sync": { "post": { "tags": [ "Session" ], "summary": "Sync the user", "description": "Asks CIHub to read again from the SCM now the installations and the\nrepositories that the person of the session reaches, at most once a\nminute.\n\n**Access**: the session of a person: the dashboard, or the command line.", "operationId": "sync_user", "responses": { "202": { "description": "CIHub takes the request." }, "401": { "description": "- `unauthorized`: No API token or session, or one that is unknown or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } } } } }, "403": { "description": "- `csrf_refused`: A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "csrf_refused": { "$ref": "#/components/examples/csrf_refused" } } } } }, "429": { "description": "- `rate_limited`: The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "The seconds to wait before the next request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } } } } }, "500": { "description": "- `internal`: The server failed; the logs of the instance say why.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal": { "$ref": "#/components/examples/internal" } } } } } }, "security": [ { "session": [] } ] } } }, "components": { "schemas": { "ActorKind": { "type": "string", "enum": [ "system", "bot", "user" ] }, "AuditEntry": { "type": "object", "description": "An action of an admin, or a change of a queue.", "required": [ "id", "action", "target", "occurred_at" ], "properties": { "action": { "type": "string", "description": "What was done: `queue.state_requested`, `queue.sync`, `repo.sync`,\n`item.cancel_requested` or `item.restart_requested`.", "example": "queue.state_requested" }, "actor_user_id": { "type": [ "string", "null" ], "description": "The user who acted; `null` for an API token.", "example": "user_06cx8fn2x6gkyc9x5csgnm5r2cyh4ryr" }, "after": { "type": [ "object", "null" ], "description": "What the action asked for." }, "before": { "type": [ "object", "null" ], "description": "What the target was before the action, when it matters." }, "id": { "type": "string", "description": "The identifier of the entry.", "example": "audit_06cx8fn2xagkyc9x5csgnm5r2hmqf441" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the action happened.", "example": "2026-10-11T09:42:00Z" }, "target": { "type": "string", "description": "The identifier of what the action changed: a queue or an item.", "example": "queue_06cx8fn2wagkyc9x5csgnm5r1gz34p81" } } }, "AuditList": { "type": "object", "description": "A page of the audit log, newest first.", "required": [ "entries", "has_more", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "How many entries the list has, every page together.", "example": 137, "minimum": 0 }, "cursor": { "type": [ "string", "null" ], "description": "The `from` of the next page; `null` on the last page.", "example": "eyJsaXN0IjoicHJzIiwiYWZ0ZXIiOlsiMjAyNi0xMC0xMVQwOTozMDowMFoiXX0" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" }, "description": "The entries of the page." }, "has_more": { "type": "boolean", "description": "More entries follow this page." } } }, "CheckConclusion": { "type": "string", "enum": [ "success", "neutral", "skipped", "failure", "error", "cancelled", "timed_out", "action_required", "stale" ] }, "CheckHealth": { "type": "object", "description": "A check over the runs that ended in a period.", "required": [ "name", "kind", "required", "runs", "failed", "passed_on_retry" ], "properties": { "failed": { "type": "integer", "format": "int64", "description": "The runs where it failed.", "example": 6, "minimum": 0 }, "kind": { "$ref": "#/components/schemas/CheckKind", "description": "`check` for a check with a run, `status` for a commit status." }, "name": { "type": "string", "description": "The name of the check or of the status.", "example": "ci / test" }, "passed_on_retry": { "type": "integer", "format": "int64", "description": "The runs where it passed after it failed on the attempt before.", "example": 4, "minimum": 0 }, "required": { "type": "boolean", "description": "A run needs it to pass." }, "runs": { "type": "integer", "format": "int64", "description": "The runs that reported it.", "example": 48, "minimum": 0 } } }, "CheckKind": { "type": "string", "enum": [ "check", "status" ] }, "CheckStatus": { "type": "string", "enum": [ "queued", "in_progress", "completed" ] }, "CliSession": { "type": "object", "description": "The session of the command line, once its person approved the code.", "required": [ "token", "login" ], "properties": { "login": { "type": "string", "description": "The login of the person on the SCM.", "example": "ada" }, "token": { "type": "string", "description": "The secret of the session, for `Authorization: Bearer`; given once.", "example": "chc_0123456789abcdefghjkmnpqrstvwx" } } }, "ConfigFile": { "type": "object", "description": "The configuration file at the head of the default branch of a\nrepository.", "required": [ "state", "entries", "strategy", "settings" ], "properties": { "column": { "type": [ "integer", "null" ], "format": "int32", "description": "The column of the error, from 1; `null` without one.", "example": 3, "minimum": 0 }, "entries": { "type": "array", "items": { "type": "string" }, "description": "The `branch` of each entry of the file, globs as written.", "example": [ "main", "release/*" ] }, "error": { "type": [ "string", "null" ], "description": "Why the file is not valid; `null` otherwise.", "example": "line 6: `batching.size` is from 1 to 100" }, "line": { "type": [ "integer", "null" ], "format": "int32", "description": "The line of the error, from 1; `null` without one.", "example": 6, "minimum": 0 }, "path": { "type": [ "string", "null" ], "description": "The path of the file: `.cihub.yaml`, `.cihub.yml`,\n`.cihub/config.yaml` or `.cihub/config.yml`; `null` without a file.", "example": ".cihub.yaml" }, "settings": { "$ref": "#/components/schemas/SettingsSummary", "description": "The settings of the default branch: from the file, or the defaults." }, "sha": { "type": [ "string", "null" ], "description": "The head of the default branch that was read; `null` when the branch\nis missing.", "example": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b1d" }, "state": { "$ref": "#/components/schemas/ConfigFileState", "description": "`none` without a file, `valid`, or `invalid`." }, "strategy": { "$ref": "#/components/schemas/Strategy", "description": "The strategy of the default branch: from the file, or the default." }, "text": { "type": [ "string", "null" ], "description": "The text of the file when it is not valid, at most 64 KiB; `null`\notherwise.", "example": "queues:\n - branch: main\n" } } }, "ConfigFileState": { "type": "string", "description": "Whether a repository has a configuration file on its default branch, and\nwhether it is valid.", "enum": [ "none", "valid", "invalid" ] }, "Dependent": { "type": "object", "description": "A live run whose predecessors hold a PR of this run.", "required": [ "run_id", "pr_numbers" ], "properties": { "pr_numbers": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "The PRs that it tests.", "example": [ 119 ] }, "run_id": { "type": "string", "description": "The identifier of the live run.", "example": "run_06cx8fn2wygkyc9x5csgnm5r24q2nbta" } } }, "DeviceCode": { "type": "object", "description": "`POST /device-codes`: a sign-in of the command line, which waits for its\nperson.", "required": [ "device_code", "user_code", "verification_url", "expires_in", "interval" ], "properties": { "device_code": { "type": "string", "description": "The secret of the command line, which it sends to\n`POST /device-codes/token`; never shown to the person.", "example": "chd_0123456789abcdefghjkmnpqrstvwx" }, "expires_in": { "type": "integer", "format": "int64", "description": "The seconds before the code expires.", "example": 900, "minimum": 0 }, "interval": { "type": "integer", "format": "int64", "description": "The seconds to wait between two requests of the session.", "example": 5, "minimum": 0 }, "user_code": { "type": "string", "description": "The code that the person checks on the page of `verification_url`.", "example": "WDJB-MJHT" }, "verification_url": { "type": "string", "description": "The page of the dashboard where the person approves the code.", "example": "https://cihub.example.com/device" } } }, "DeviceCodeToken": { "type": "object", "description": "`POST /device-codes/token`: the device code of the sign-in.", "required": [ "device_code" ], "properties": { "device_code": { "type": "string", "description": "The `device_code` that `POST /device-codes` gave.", "example": "chd_0123456789abcdefghjkmnpqrstvwx" } } }, "ErrorCode": { "type": "string", "description": "The machine code of an error: a client decides on it, never on\n`detail`. Each code has one HTTP status.", "enum": [ "invalid_request", "limit_out_of_range", "invalid_cursor", "unknown_priority", "device_code_pending", "device_code_expired", "unauthorized", "scope_missing", "csrf_refused", "device_code_denied", "route_not_found", "org_not_found", "repo_not_found", "queue_not_found", "pr_not_found", "run_not_found", "device_code_not_found", "pr_already_queued", "item_ended", "item_not_in_test", "rate_limited", "too_many_streams", "polling_too_fast", "internal", "sign_in_unavailable", "scm_unavailable" ] }, "Event": { "type": "object", "description": "An event of the log of a queue about a PR.", "required": [ "id", "seq", "item_id", "type", "actor_kind", "occurred_at", "description", "payload" ], "properties": { "actor": { "type": [ "string", "null" ], "description": "The login of the person who acted, or whose request caused the\ndecision; `null` when CIHub or an API token did.", "example": "ada" }, "actor_kind": { "$ref": "#/components/schemas/ActorKind", "description": "`system` for CIHub, `bot` for the account that CIHub acts with on the\nSCM, `user` for a person." }, "description": { "type": "string", "description": "What happened, in English, for a person, where a check or a condition\nis a Markdown code span; it can change without notice, unlike `type`\nand `payload`.", "example": "all the required checks passed" }, "id": { "type": "string", "description": "The identifier of the event.", "example": "event_06cx8fn2x2gkyc9x5csgnm5r2b89wbcv" }, "item_id": { "type": "string", "description": "The submission of the PR that the event concerns.", "example": "item_06cx8fn2wegkyc9x5csgnm5r1ngcahzx" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event happened.", "example": "2026-10-11T09:42:00Z" }, "payload": { "type": "object", "description": "The facts of the event, whose fields depend on `type`." }, "seq": { "type": "integer", "format": "int64", "description": "The sequence number of the event in the log of the queue.", "example": 4182 }, "type": { "$ref": "#/components/schemas/EventType", "description": "The type of the event, `.`." } } }, "EventList": { "type": "object", "description": "A page of the events of a PR, oldest first.", "required": [ "events", "has_more", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "How many entries the list has, every page together.", "example": 137, "minimum": 0 }, "cursor": { "type": [ "string", "null" ], "description": "The `from` of the next page; `null` on the last page.", "example": "eyJsaXN0IjoicHJzIiwiYWZ0ZXIiOlsiMjAyNi0xMC0xMVQwOTozMDowMFoiXX0" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "description": "The events of the page." }, "has_more": { "type": "boolean", "description": "More entries follow this page." } } }, "EventType": { "type": "string", "enum": [ "item.submitted", "item.cancel_requested", "item.restart_requested", "pr.observed", "target.pushed", "check.observed", "targets.received", "test_branch.assembled", "test_branch.assembly_failed", "merge.succeeded", "merge.failed", "queue.control_requested", "queue.settings_changed", "access.lost", "access.restored", "item.transitioned", "item.readiness_changed", "queue.renumbered", "group.formed", "group.transitioned", "run.transitioned", "queue.transitioned", "queue.window_changed" ] }, "Finding": { "type": "object", "description": "A point of the configuration of the SCM that the queue needs.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "`update_restriction_missing`, `app_not_exempt`,\n`test_branches_not_excluded`, `up_to_date_required`,\n`conditions_status_required` or `target_branch_missing`.", "example": "app_not_exempt" }, "message": { "type": "string", "description": "What to change, in English, for a person.", "example": "add the App to the bypass list of the ruleset, in exempt mode" } } }, "Graph": { "type": "object", "description": "The merge graph: the head of the target branch, the live items, the\npredecessors that their tests merge before them, and the live runs.", "required": [ "nodes", "edges", "runs" ], "properties": { "edges": { "type": "array", "items": { "$ref": "#/components/schemas/GraphEdge" }, "description": "An edge from each predecessor of a live item, which its test merges\nbefore it." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/GraphNode" }, "description": "The live items, in the order of the queue." }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/GraphRun" }, "description": "The last run of each live group, the oldest first." }, "target_head_sha": { "type": [ "string", "null" ], "description": "The head of the target branch that the queue saw last; `null` before\nthe first.", "example": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b1d" } } }, "GraphEdge": { "type": "object", "description": "The test of `to` merges `from` before it.", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "description": "The identifier of the predecessor.", "example": "item_06cx8fn2wjgkyc9x5csgnm5r1v8fe0y4" }, "to": { "type": "string", "description": "The identifier of the item whose test merges `from` first.", "example": "item_06cx8fn2wegkyc9x5csgnm5r1ngcahzx" } } }, "GraphNode": { "type": "object", "description": "A live item of the graph.", "required": [ "item_id", "pr_number", "state" ], "properties": { "item_id": { "type": "string", "description": "The identifier of the item.", "example": "item_06cx8fn2wegkyc9x5csgnm5r1ngcahzx" }, "position": { "type": [ "integer", "null" ], "format": "int64", "description": "The order in the queue, lower first; `null` before the admission.", "example": 1000 }, "pr_number": { "type": "integer", "format": "int64", "description": "The number of the PR in its repository.", "example": 118, "minimum": 0 }, "state": { "$ref": "#/components/schemas/ItemState", "description": "The state of the item." } } }, "GraphRun": { "type": "object", "description": "A run of the graph: the items that it tests, on top of their\npredecessors.", "required": [ "run_id", "item_ids", "predecessor_ids", "attempt", "status", "started_at" ], "properties": { "attempt": { "type": "integer", "format": "int32", "description": "From 1; a run tested again within the failure budget has a higher\nattempt.", "example": 1, "minimum": 0 }, "item_ids": { "type": "array", "items": { "type": "string" }, "description": "The items that the run tests.", "example": [ "item_06cx8fn2wegkyc9x5csgnm5r1ngcahzx" ] }, "predecessor_ids": { "type": "array", "items": { "type": "string" }, "description": "The items that the test branch merges before them.", "example": [ "item_06cx8fn2wjgkyc9x5csgnm5r1v8fe0y4" ] }, "run_id": { "type": "string", "description": "The identifier of the run.", "example": "run_06cx8fn2wtgkyc9x5csgnm5r22ca6g0w" }, "started_at": { "type": "string", "format": "date-time", "description": "When the run started.", "example": "2026-10-11T09:33:00Z" }, "status": { "$ref": "#/components/schemas/RunStatus", "description": "The status of the run." } } }, "HealthBucket": { "type": "object", "description": "The PRs that ended in an hour or a day of the period.", "required": [ "start", "merged", "failed" ], "properties": { "failed": { "type": "integer", "format": "int64", "description": "The PRs that failed in the bucket.", "example": 1, "minimum": 0 }, "merged": { "type": "integer", "format": "int64", "description": "The PRs that merged in the bucket.", "example": 4, "minimum": 0 }, "start": { "type": "string", "format": "date-time", "description": "The start of the hour or of the day.", "example": "2026-10-14T09:00:00Z" }, "time_to_merge": { "oneOf": [ { "$ref": "#/components/schemas/TimeToMerge", "description": "`null` when no PR merged." }, { "type": "null" } ] } } }, "HealthTotals": { "type": "object", "description": "The PRs that ended in a period.", "required": [ "merged", "failed", "cancelled" ], "properties": { "cancelled": { "type": "integer", "format": "int64", "description": "The PRs that a person cancelled, or that left the queue on a change of the PR.", "example": 2, "minimum": 0 }, "failed": { "type": "integer", "format": "int64", "description": "The PRs that failed.", "example": 3, "minimum": 0 }, "merged": { "type": "integer", "format": "int64", "description": "The PRs that merged.", "example": 42, "minimum": 0 }, "time_to_merge": { "oneOf": [ { "$ref": "#/components/schemas/TimeToMerge", "description": "`null` when no PR merged." }, { "type": "null" } ] } } }, "HealthVerdict": { "oneOf": [ { "type": "object", "description": "No PR merged or failed.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "quiet" ] } } }, { "type": "object", "description": "The PRs merge, and few fail.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "healthy" ] } } }, { "type": "object", "description": "More than 15 % of the PRs that merged or failed failed.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "many_failures" ] } } }, { "type": "object", "description": "A check failed, then passed on the next attempt of its run, at least 3\ntimes: each retry costs a run and makes the PRs behind wait.", "required": [ "check", "times", "kind" ], "properties": { "check": { "type": "string", "description": "The name of the check.", "example": "ci / test" }, "kind": { "type": "string", "enum": [ "check_passes_on_retry" ] }, "times": { "type": "integer", "format": "int64", "description": "How many times it passed on a retry.", "example": 4, "minimum": 0 } } } ], "description": "The first thing to know about a queue over the period." }, "Instance": { "type": "object", "description": "`GET /instance`: the instance of CIHub.", "required": [ "version" ], "properties": { "app_install_url": { "type": [ "string", "null" ], "description": "The page of the SCM that installs the App on an account, or chooses\nthe repositories of its installation; `null` when the SCM did not\nanswer.", "example": "https://scm.example.com/apps/cihub/installations/new" }, "version": { "type": "string", "description": "The version of the instance.", "example": "0.1.0" } } }, "ItemCounts": { "type": "object", "description": "The current items of a queue in each state that is not terminal.", "required": [ "not_ready", "pending", "testing", "pending_failure", "tests_passed" ], "properties": { "not_ready": { "type": "integer", "format": "int32", "description": "Submitted, and blocked by a condition of the PR.", "example": 2, "minimum": 0 }, "pending": { "type": "integer", "format": "int32", "description": "Admitted, and waiting for a run.", "example": 3, "minimum": 0 }, "pending_failure": { "type": "integer", "format": "int32", "description": "In a run that failed, while the queue learns who is at fault.", "example": 0, "minimum": 0 }, "testing": { "type": "integer", "format": "int32", "description": "In a run in progress.", "example": 4, "minimum": 0 }, "tests_passed": { "type": "integer", "format": "int32", "description": "Proved by a run, and waiting for the merge.", "example": 1, "minimum": 0 } } }, "ItemState": { "type": "string", "enum": [ "not_ready", "pending", "testing", "tests_passed", "pending_failure", "merged", "failed", "cancelled" ] }, "MembershipRole": { "type": "string", "enum": [ "admin", "member" ] }, "MergeMethod": { "type": "string", "enum": [ "squash", "merge_commit", "rebase", "fast_forward" ] }, "Org": { "type": "object", "description": "An organization: the account of an installation of the App.", "required": [ "slug", "is_suspended" ], "properties": { "avatar_url": { "type": [ "string", "null" ], "description": "The address of the image of the account on the SCM, `null` when the\nSCM gives none or until CIHub reads it.", "example": "https://avatars.example.com/u/70" }, "description": { "type": [ "string", "null" ], "description": "The description that the account gives on the SCM, `null` when it\ngives none or until CIHub reads it.", "example": "Rockets and anvils" }, "is_suspended": { "type": "boolean", "description": "Every connection of the organization to the SCM is suspended: CIHub\nreaches none of its accounts, and its queues are paused." }, "name": { "type": [ "string", "null" ], "description": "The name that the account gives on the SCM, `null` when it gives none\nor until CIHub reads it.", "example": "Acme" }, "role": { "oneOf": [ { "$ref": "#/components/schemas/MembershipRole", "description": "The role of the person of the session: `admin` has every scope,\n`member` has `queues:read` and `prs:write`; `null` for an API token." }, { "type": "null" } ] }, "slug": { "type": "string", "description": "The slug of the organization, as the routes name it.", "example": "acme" } } }, "OrgList": { "type": "object", "description": "A page of the organizations of the person, by slug.", "required": [ "orgs", "has_more", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "How many entries the list has, every page together.", "example": 137, "minimum": 0 }, "cursor": { "type": [ "string", "null" ], "description": "The `from` of the next page; `null` on the last page.", "example": "eyJsaXN0IjoicHJzIiwiYWZ0ZXIiOlsiMjAyNi0xMC0xMVQwOTozMDowMFoiXX0" }, "has_more": { "type": "boolean", "description": "More entries follow this page." }, "orgs": { "type": "array", "items": { "$ref": "#/components/schemas/Org" }, "description": "The organizations of the page." } } }, "Permission": { "type": "object", "description": "What the caller may do on a repository: `read` its queues, its PRs and\nits setup; `write`: submit, cancel and restart a PR; `admin`: change the\nstate of a queue and read a setup or a queue again from the SCM.", "required": [ "read", "write", "admin" ], "properties": { "admin": { "type": "boolean", "description": "The caller acts on the queues and the setup of the repository." }, "read": { "type": "boolean", "description": "The caller reads the repository." }, "write": { "type": "boolean", "description": "The caller acts on the PRs of the repository." } } }, "Person": { "type": "object", "description": "A person on the SCM.", "required": [ "login" ], "properties": { "avatar_url": { "type": [ "string", "null" ], "description": "The address of the image of the person on the SCM, `null` until CIHub\nreads it at their sign-in or in the members of an account.", "example": "https://avatars.example.com/u/1" }, "login": { "type": "string", "description": "The login of the person on the SCM.", "example": "ada" } } }, "Pr": { "type": "object", "description": "A PR in a queue: its last submission. A PR submitted again gets a new\nsubmission, whose history its events keep.", "required": [ "id", "queue_id", "repo", "queue", "number", "author", "head_sha", "state", "state_reason", "state_description", "state_changed_at", "priority", "block_reasons", "no_batch", "submitted_via", "submitted_at", "ahead" ], "properties": { "ahead": { "type": "array", "items": { "$ref": "#/components/schemas/PrAhead" }, "description": "The admitted PRs that merge before it, the head of the queue first;\nempty for a merged item. For an item not admitted yet, every admitted\nPR: a PR of a higher priority goes before some of them." }, "author": { "$ref": "#/components/schemas/Person", "description": "The author of the PR." }, "block_reasons": { "type": "array", "items": { "type": "object" }, "description": "What keeps a `not_ready` item out of the queue. Each one has a `kind`:\n`review_required` (`have`, `need`), `changes_requested`,\n`failing_required_check` (`check`), `awaiting_required_check`\n(`check`, `status`: `missing`, `queued` or `running`), `behind_base`,\n`merge_conflict`, `stack_needs_rebase` (`onto_pr_number`),\n`undetermined`, or\n`queue_conditions_unmet` (`conditions`).", "example": [ { "have": 0, "kind": "review_required", "need": 1 } ] }, "group_id": { "type": [ "string", "null" ], "description": "The identifier of the test group of the item; `null` outside a group.", "example": "group_06cx8fn2wpgkyc9x5csgnm5r1ygtt5k0" }, "head_sha": { "type": "string", "description": "The head of the PR that the item tests.", "example": "3b5d7f91a2c4e6081b3d5f7a9c1e3b5d7f9a1c3e" }, "id": { "type": "string", "description": "The identifier of the submission.", "example": "item_06cx8fn2wegkyc9x5csgnm5r1ngcahzx" }, "merged_sha": { "type": [ "string", "null" ], "description": "The commit that the merge of the PR created on the target branch;\n`null` before the merge.", "example": "c4e6081b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c" }, "merges_in_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "About how many seconds until it merges, from the median duration of\nthe runs of its queue; `null` when it does not move toward the merge,\nor when its queue has no run that succeeded in the last 24 hours.", "example": 1080, "minimum": 0 }, "no_batch": { "type": "boolean", "description": "The PR is tested alone, never in a batch." }, "number": { "type": "integer", "format": "int64", "description": "The number of the PR in its repository.", "example": 118, "minimum": 0 }, "position": { "type": [ "integer", "null" ], "format": "int64", "description": "The order in the queue, lower first; `null` before the admission.", "example": 1000 }, "priority": { "type": "integer", "format": "int32", "description": "From 0 to 255, lower first: `urgent` is 0, `high` 10, `medium` 100,\n`low` 200.", "example": 100, "minimum": 0 }, "profile": { "type": [ "string", "null" ], "description": "The profile of the queue that gives the settings of the PR (its merge\nmethod, its batches, its failure budget); `null` for those of the\nqueue.", "example": "dependencies" }, "queue": { "type": "string", "description": "The target branch of the queue, as the routes name it.", "example": "main" }, "queue_id": { "type": "string", "description": "The identifier of the queue of the item.", "example": "queue_06cx8fn2wagkyc9x5csgnm5r1gz34p81" }, "repo": { "type": "string", "description": "The name of the repository of the queue, as the routes name it.", "example": "web" }, "run_id": { "type": [ "string", "null" ], "description": "The last run of the group of the item: the run that tests it, or\nthat tested it last; `null` outside a group.", "example": "run_06cx8fn2wtgkyc9x5csgnm5r22ca6g0w" }, "state": { "$ref": "#/components/schemas/ItemState", "description": "`not_ready` waits for a condition of the PR; `pending` waits for a run;\n`testing` is in a run; `pending_failure` is in a run that failed, while\nthe queue learns who is at fault; `tests_passed` waits for the merge;\n`merged`, `failed` and `cancelled` end the item." }, "state_changed_at": { "type": "string", "format": "date-time", "description": "When the item reached its state.", "example": "2026-10-11T09:42:00Z" }, "state_description": { "type": "string", "description": "The sentence of `state_reason`, in English, for a person; it can\nchange without notice, unlike `state_reason`.", "example": "all the required checks passed" }, "state_reason": { "$ref": "#/components/schemas/Reason", "description": "Why the item reached its state: a code of the closed vocabulary\n(`specs/DOMAIN.md`). A client decides on it." }, "submitted_at": { "type": "string", "format": "date-time", "description": "When the PR was submitted.", "example": "2026-10-11T09:30:00Z" }, "submitted_by": { "type": [ "string", "null" ], "description": "The login of the person who submitted the PR; `null` when CIHub or an\nAPI token did.", "example": "ada" }, "submitted_via": { "$ref": "#/components/schemas/SubmittedVia", "description": "How the PR came into the queue: a `/cihub merge` comment, a label,\nor the API." }, "title": { "type": [ "string", "null" ], "description": "The title at the last read of the PR; `null` before the first.", "example": "Export invoices as CSV" }, "url": { "type": [ "string", "null" ], "description": "The page of the PR on the SCM, at the last read of the PR; `null`\nbefore the first.", "example": "https://github.com/acme/web/pull/118" } } }, "PrAhead": { "type": "object", "description": "A PR ahead of another one in its queue.", "required": [ "pr_number", "state" ], "properties": { "pr_number": { "type": "integer", "format": "int64", "description": "The number of the PR in its repository.", "example": 117, "minimum": 0 }, "state": { "$ref": "#/components/schemas/ItemState", "description": "The state of its item." } } }, "PrList": { "type": "object", "description": "A page of PRs.", "required": [ "prs", "has_more", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "How many entries the list has, every page together.", "example": 137, "minimum": 0 }, "cursor": { "type": [ "string", "null" ], "description": "The `from` of the next page; `null` on the last page.", "example": "eyJsaXN0IjoicHJzIiwiYWZ0ZXIiOlsiMjAyNi0xMC0xMVQwOTozMDowMFoiXX0" }, "has_more": { "type": "boolean", "description": "More entries follow this page." }, "prs": { "type": "array", "items": { "$ref": "#/components/schemas/Pr" }, "description": "The PRs of the page." } } }, "PriorityInput": { "oneOf": [ { "type": "integer", "format": "int32", "minimum": 0 }, { "type": "string" } ], "description": "The priority of a submission: a name (`urgent`, `high`, `medium`, `low`)\nor a value from 0 to 255, lower first." }, "Problem": { "type": "object", "description": "An error, as `application/problem+json` (RFC 9457).", "required": [ "type", "title", "status", "detail", "code" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode", "description": "The machine code of the error: decide on it." }, "detail": { "type": "string", "description": "What went wrong with this request, in English, for a person; it can\nchange without notice, unlike `code`.", "example": "no queue of `main`" }, "status": { "type": "integer", "format": "int32", "description": "The HTTP status of the answer.", "example": 404, "minimum": 0 }, "title": { "type": "string", "description": "The reason phrase of the HTTP status.", "example": "Not Found" }, "type": { "type": "string", "description": "The page of the documentation that explains `code`.", "example": "https://cihub.io/docs/api/errors#queue_not_found" } } }, "Queue": { "type": "object", "description": "A queue of a target branch, with its counters and its settings.", "required": [ "id", "repo_id", "repo", "target_branch", "is_default_branch", "state", "mode", "state_changed_at", "created_at", "updated_at", "strategy", "is_suspended", "has_config_file", "counts", "merged_last_24h", "failed_last_24h", "failed_or_cancelled_last_24h", "live_runs", "window", "settings", "setup" ], "properties": { "config_error": { "type": [ "string", "null" ], "description": "Why the last file read is not valid; the queue keeps the last valid\none.", "example": "line 4: `batching.size` is from 1 to 100" }, "config_sha": { "type": [ "string", "null" ], "description": "The head of the target whose configuration file the queue read last.", "example": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b1d" }, "counts": { "$ref": "#/components/schemas/ItemCounts", "description": "The current items of the queue in each state that is not terminal." }, "created_at": { "type": "string", "format": "date-time", "description": "When the first command on the target branch created the queue.", "example": "2026-10-11T09:00:00Z" }, "failed_last_24h": { "type": "integer", "format": "int32", "description": "The current items that reached `failed` in the 24 hours before the\nrequest.", "example": 1, "minimum": 0 }, "failed_or_cancelled_last_24h": { "type": "integer", "format": "int32", "description": "The current items that reached `failed` or `cancelled` in the 24 hours\nbefore the request, as the list of the PRs gives them.", "example": 2, "minimum": 0 }, "has_config_file": { "type": "boolean", "description": "The target branch has a configuration file, valid or not; without\nit, the queue takes the defaults." }, "id": { "type": "string", "description": "The identifier of the queue.", "example": "queue_06cx8fn2wagkyc9x5csgnm5r1gz34p81" }, "is_default_branch": { "type": "boolean", "description": "The branch of the queue is the default branch of its repository." }, "is_suspended": { "type": "boolean", "description": "CIHub no longer reaches the repository of the queue on the SCM: the\nApp is suspended or uninstalled, or no longer reaches the repository.\nThe queue is stopped until the access comes back, and `state` keeps\nthe state that it takes again then." }, "last_merged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the last current item reached `merged`; `null` if no item merged.", "example": "2026-10-11T09:42:00Z" }, "live_runs": { "type": "integer", "format": "int32", "description": "The runs in progress.", "example": 2, "minimum": 0 }, "median_run_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "The median duration of the runs that succeeded in the last 24 hours,\nin seconds; `null` without such a run.", "example": 540, "minimum": 0 }, "merged_last_24h": { "type": "integer", "format": "int32", "description": "The current items that reached `merged` in the 24 hours before the\nrequest.", "example": 17, "minimum": 0 }, "mode": { "$ref": "#/components/schemas/QueueMode", "description": "`single` tests every PR on top of all those ahead of it; `parallel`\nonly on top of those that change the same targets." }, "repo": { "type": "string", "description": "The name of the repository of the queue, as the routes name it.", "example": "web" }, "repo_id": { "type": "string", "description": "The identifier of the repository of the queue.", "example": "repo_06cx8fn2w6gkyc9x5csgnm5r1dmqz3s0" }, "settings": { "$ref": "#/components/schemas/SettingsSummary", "description": "The settings of the last valid configuration file." }, "setup": { "$ref": "#/components/schemas/Setup", "description": "What the last setup read found about the rules of the SCM that the\nqueue needs." }, "state": { "$ref": "#/components/schemas/QueueState", "description": "`running` accepts and merges; `paused` tests and merges nothing and\nkeeps the order, and a submission waits for the resume; `draining`\naccepts nothing and lets the items in flight merge; `switching_modes`\nbehaves as `draining` until the queue is empty." }, "state_changed_at": { "type": "string", "format": "date-time", "description": "When the queue reached its state; its creation before a first change.", "example": "2026-10-11T09:42:00Z" }, "state_changed_by": { "type": [ "string", "null" ], "description": "The login of the person who asked for the state; `null` when CIHub\ndecided it, or when an API token asked for it.", "example": "ada" }, "strategy": { "$ref": "#/components/schemas/Strategy", "description": "The strategy of the last valid configuration file." }, "target_branch": { "type": "string", "description": "The branch that the queue merges into, which names the queue in the\nroutes: a repository has one queue per branch.", "example": "main" }, "target_head_sha": { "type": [ "string", "null" ], "description": "The head of the target branch that the queue saw last; `null` before\nthe first.", "example": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b1d" }, "updated_at": { "type": "string", "format": "date-time", "description": "The last change of the state, the mode or the configuration file of\nthe queue.", "example": "2026-10-11T09:42:00Z" }, "window": { "$ref": "#/components/schemas/Window", "description": "How many runs the queue keeps in progress." } } }, "QueueChanged": { "type": "object", "description": "The event `queue_changed` of `GET /orgs/{org}/stream`: what the pages of\nthe queue show changed, and they read it again.", "required": [ "queue_id", "seq" ], "properties": { "queue_id": { "type": "string", "description": "The identifier of the queue that changed.", "example": "queue_06cx8fn2wagkyc9x5csgnm5r1gz34p81" }, "seq": { "type": "integer", "format": "int64", "description": "The sequence number of the last event of the log of the queue; 0\nbefore the first.", "example": 4182 } } }, "QueueHealth": { "type": "object", "description": "What a queue did over a period, against the period of the same length\nbefore it: the PRs that ended, how long they took to merge, why the others\nleft, and the checks of its runs. A period ends with the hour, or the UTC\nday, that holds now.", "required": [ "from", "to", "verdict", "current", "previous", "buckets", "time_in_states", "left_without_merge", "checks" ], "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/HealthBucket" }, "description": "The period cut in hours (`24h`) or in UTC days (`7d`, `30d`), the oldest first." }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckHealth" }, "description": "The checks of the runs that ended in the period, by name." }, "current": { "$ref": "#/components/schemas/HealthTotals", "description": "The PRs that ended in the period." }, "from": { "type": "string", "format": "date-time", "description": "The start of the period.", "example": "2026-10-13T10:00:00Z" }, "left_without_merge": { "type": "array", "items": { "$ref": "#/components/schemas/ReasonCount" }, "description": "Why the other PRs ended without a merge, the most frequent reason first." }, "previous": { "$ref": "#/components/schemas/HealthTotals", "description": "The PRs that ended in the period before." }, "time_in_states": { "type": "array", "items": { "$ref": "#/components/schemas/StateTime" }, "description": "The median time that the PRs merged in the period spent in each\nstate before their merge, in the order of the states." }, "to": { "type": "string", "format": "date-time", "description": "The end of the period, excluded.", "example": "2026-10-14T10:00:00Z" }, "verdict": { "$ref": "#/components/schemas/HealthVerdict", "description": "The first thing to know about the queue over the period." } } }, "QueueList": { "type": "object", "description": "A page of queues, by repository name then target branch.", "required": [ "queues", "has_more", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "How many entries the list has, every page together.", "example": 137, "minimum": 0 }, "cursor": { "type": [ "string", "null" ], "description": "The `from` of the next page; `null` on the last page.", "example": "eyJsaXN0IjoicHJzIiwiYWZ0ZXIiOlsiMjAyNi0xMC0xMVQwOTozMDowMFoiXX0" }, "has_more": { "type": "boolean", "description": "More entries follow this page." }, "queues": { "type": "array", "items": { "$ref": "#/components/schemas/Queue" }, "description": "The queues of the page." } } }, "QueueMode": { "type": "string", "enum": [ "single", "parallel" ] }, "QueueState": { "type": "string", "enum": [ "running", "paused", "draining", "switching_modes" ] }, "Reason": { "type": "string", "enum": [ "submitted", "merge_item_now_ready", "test_run_started", "failure_budget_retry", "manual_push_to_target_branch", "prerequisite_merge_item_failed", "prerequisite_merge_item_cancelled", "prerequisite_merge_item_manually_merged", "batch_member_left", "tests_restarted_by_user", "tests_restarted_by_api_request", "skip_the_line_interrupted", "bisection_required", "bisection_test_run_passed", "test_run_passed", "successor_test_run_passed", "passed_by_optimization", "merge_graph_merge", "merge_graph_direct_merge", "manual_merge", "user_requested", "admin_requested", "pr_closed", "pr_pushed_to", "pr_base_branch_changed", "pr_converted_to_draft", "label_removed", "not_ready_timeout_expired", "start_test_run_invalid_event", "start_test_run_merge_conflict", "start_test_run_config_parsing_failure", "start_test_run_config_bad_version", "start_test_run_config_missing_required_statuses", "start_test_run_config_bad_required_statuses", "start_test_run_no_required_statuses", "start_test_run_retry_exhausted", "start_test_run_draft_prs_not_allowed", "start_test_run_permissions_block_test_branch", "test_run_required_status_failed", "test_run_timeout", "merge_rejected", "direct_merge_rejected", "merge_rate_limit_exceeded", "merge_branch_protection_unmet", "merge_already_in_progress", "merge_repeated_server_errors", "pr_updated_at_merge_time", "test_branch_assembled", "mode_changed", "mode_switch_completed", "queue_draining", "queue_switching_modes" ] }, "ReasonCount": { "type": "object", "description": "How many PRs ended for a reason.", "required": [ "conclusion", "reason", "description", "count" ], "properties": { "conclusion": { "$ref": "#/components/schemas/ItemState", "description": "`failed` or `cancelled`." }, "count": { "type": "integer", "format": "int64", "description": "How many PRs ended for this reason.", "example": 3, "minimum": 0 }, "description": { "type": "string", "description": "The reason for a person, as the comment of a PR gives it.", "example": "a required check failed" }, "reason": { "$ref": "#/components/schemas/Reason", "description": "Why the PRs ended." } } }, "Repo": { "type": "object", "description": "A repository of the organization, with what the caller may do on it and\nthe verdict of its setup; `RepoDetail` gives its whole setup.", "required": [ "id", "owner", "name", "default_branch", "created_at", "updated_at", "permission", "setup" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When CIHub first read the repository from the SCM.", "example": "2026-10-11T09:00:00Z" }, "default_branch": { "type": "string", "description": "The default branch of the repository.", "example": "main" }, "id": { "type": "string", "description": "The identifier of the repository.", "example": "repo_06cx8fn2w6gkyc9x5csgnm5r1dmqz3s0" }, "name": { "type": "string", "description": "The name of the repository, as the routes name it.", "example": "web" }, "owner": { "type": "string", "description": "The account of the repository on the SCM.", "example": "acme" }, "permission": { "$ref": "#/components/schemas/Permission", "description": "What the caller may do on the repository." }, "setup": { "$ref": "#/components/schemas/SetupSummary", "description": "The verdict of the setup of the repository." }, "updated_at": { "type": "string", "format": "date-time", "description": "When a read of the SCM last changed its owner, its name or its default\nbranch, or removed or restored it.", "example": "2026-10-11T09:42:00Z" } } }, "RepoDetail": { "type": "object", "description": "A repository of the organization, with what the caller may do on it and\nits whole setup.", "required": [ "id", "owner", "name", "default_branch", "created_at", "updated_at", "permission", "setup" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When CIHub first read the repository from the SCM.", "example": "2026-10-11T09:00:00Z" }, "default_branch": { "type": "string", "description": "The default branch of the repository.", "example": "main" }, "id": { "type": "string", "description": "The identifier of the repository.", "example": "repo_06cx8fn2w6gkyc9x5csgnm5r1dmqz3s0" }, "name": { "type": "string", "description": "The name of the repository, as the routes name it.", "example": "web" }, "owner": { "type": "string", "description": "The account of the repository on the SCM.", "example": "acme" }, "permission": { "$ref": "#/components/schemas/Permission", "description": "What the caller may do on the repository." }, "setup": { "$ref": "#/components/schemas/RepoSetup", "description": "What CIHub found about the rules and the configuration file of the\ndefault branch." }, "updated_at": { "type": "string", "format": "date-time", "description": "When a read of the SCM last changed its owner, its name or its default\nbranch, or removed or restored it.", "example": "2026-10-11T09:42:00Z" } } }, "RepoList": { "type": "object", "description": "A page of repositories, by owner then name.", "required": [ "repos", "has_more", "count" ], "properties": { "count": { "type": "integer", "format": "int64", "description": "How many entries the list has, every page together.", "example": 137, "minimum": 0 }, "cursor": { "type": [ "string", "null" ], "description": "The `from` of the next page; `null` on the last page.", "example": "eyJsaXN0IjoicHJzIiwiYWZ0ZXIiOlsiMjAyNi0xMC0xMVQwOTozMDowMFoiXX0" }, "has_more": { "type": "boolean", "description": "More entries follow this page." }, "repos": { "type": "array", "items": { "$ref": "#/components/schemas/Repo" }, "description": "The repositories of the page." } } }, "RepoSetup": { "type": "object", "description": "The setup of a repository: what CIHub found about the rules of its\ndefault branch and its configuration file, with a verdict. Every field\ncomes from Postgres: showing a setup calls the SCM zero times.", "required": [ "state", "rules", "target_branch_missing" ], "properties": { "checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When CIHub read the setup; `null` before the first read.", "example": "2026-10-16T09:00:00Z" }, "config": { "oneOf": [ { "$ref": "#/components/schemas/ConfigFile", "description": "The configuration file at the head of the default branch; `null`\nbefore the first read." }, { "type": "null" } ] }, "queue": { "type": [ "string", "null" ], "description": "The target branch of the queue of the default branch, with `started`;\n`null` otherwise.", "example": "main" }, "requested_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When an admin asked to read the setup again, while that read waits;\n`null` otherwise.", "example": "2026-10-16T09:05:00Z" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleCheck" }, "description": "The four rules that a queue needs, always in this order:\n`update_restriction_missing`, `app_not_exempt`,\n`test_branches_not_excluded`, `up_to_date_required`; empty before the\nfirst read." }, "rules_url": { "type": [ "string", "null" ], "description": "The page of the SCM that changes the rules of the repository; `null`\nwhen the SCM has none.", "example": "https://scm.example.com/acme/web/settings/rules" }, "state": { "$ref": "#/components/schemas/SetupState", "description": "The verdict of the setup." }, "target_branch_missing": { "type": "boolean", "description": "The default branch did not exist at the last read: no queue can merge\ninto it." } } }, "RequestedQueueState": { "type": "string", "description": "The state that `PATCH /orgs/{org}/repos/{repo}/queues/{queue}` asks for.", "enum": [ "running", "paused", "draining" ] }, "RequiredStatusesSource": { "type": "string", "enum": [ "repo_config", "branch_protection" ] }, "RuleCheck": { "type": "object", "description": "A rule of the SCM that a queue needs, and whether the default branch has\nit.", "required": [ "code", "passed", "blocks_merge", "title" ], "properties": { "blocks_merge": { "type": "boolean", "description": "The queue cannot merge while the rule fails (`app_not_exempt`,\n`test_branches_not_excluded`)." }, "code": { "type": "string", "description": "`update_restriction_missing`, `app_not_exempt`,\n`test_branches_not_excluded` or `up_to_date_required`: the finding\nwhen the rule fails.", "example": "app_not_exempt" }, "message": { "type": [ "string", "null" ], "description": "What to change, in English, for a person, when the rule fails; `null`\nwhen it passes.", "example": "add the App to the bypass list of the ruleset, in exempt mode" }, "passed": { "type": "boolean", "description": "The default branch has the rule." }, "title": { "type": "string", "description": "The rule, in English, for a person: what passes, or what fails.", "example": "The CIHub App is exempt from it" } } }, "Run": { "type": "object", "description": "A run: one test, on the CI, of a test branch that CIHub assembles from\nthe head of the target branch, the PRs ahead (the predecessors), then the\nPRs that it tests. The name of the test branch ends with the identifier of\nthe run.", "required": [ "id", "queue_id", "group_id", "attempt", "status", "status_reason", "test_branch", "base_sha", "tested_pr_numbers", "head_shas", "predecessor_pr_numbers", "required_statuses", "started_at", "failure_causing_statuses", "checks", "dependents" ], "properties": { "attempt": { "type": "integer", "format": "int32", "description": "From 1; a run tested again within the failure budget has a higher\nattempt.", "example": 1, "minimum": 0 }, "base_sha": { "type": "string", "description": "The head of the target branch that the test branch starts from.", "example": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b1d" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/RunCheck" }, "description": "Every check and status observed on `test_sha`." }, "conflict_culprit": { "type": [ "object", "null" ], "description": "What a member conflicts with, when the assembly of the test branch\nfailed: `{\"kind\": \"queue_pr\", \"pr_number\": 117}` or\n`{\"kind\": \"base_branch\"}`." }, "dependents": { "type": "array", "items": { "$ref": "#/components/schemas/Dependent" }, "description": "The live runs whose predecessors hold a PR of this run." }, "draft_pr_number": { "type": [ "integer", "null" ], "format": "int64", "description": "The draft PR that runs the CI of the test branch, when the\nconfiguration asks for one.", "example": 412, "minimum": 0 }, "draft_pr_url": { "type": [ "string", "null" ], "description": "The page of the draft PR on the SCM; `null` without a draft PR.", "example": "https://github.com/acme/web/pull/412" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the run ended; `null` while it runs.", "example": "2026-10-11T09:42:00Z" }, "failure_causing_statuses": { "type": "array", "items": { "type": "string" }, "description": "The required checks that failed the run.", "example": [] }, "failure_reason": { "oneOf": [ { "$ref": "#/components/schemas/Reason", "description": "`status_reason` when the run `failed` or `timed_out`; `null` otherwise." }, { "type": "null" } ] }, "group_id": { "type": "string", "description": "The identifier of the test group that the run tests.", "example": "group_06cx8fn2wpgkyc9x5csgnm5r1ygtt5k0" }, "head_shas": { "type": "array", "items": { "type": "string" }, "description": "The heads merged in order: the predecessors, then the members.", "example": [ "3b5d7f91a2c4e6081b3d5f7a9c1e3b5d7f9a1c3e" ] }, "id": { "type": "string", "description": "The identifier of the run.", "example": "run_06cx8fn2wtgkyc9x5csgnm5r22ca6g0w" }, "impacted_targets": { "type": [ "object", "null" ], "description": "The targets that the tested PRs change (lot 13); `null` until then." }, "last_report_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When CIHub saw the last report of a check of the run.", "example": "2026-10-11T09:40:00Z" }, "predecessor_pr_numbers": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "The PRs that the test branch merges before the tested ones.", "example": [ 117 ] }, "queue_id": { "type": "string", "description": "The identifier of the queue of the run.", "example": "queue_06cx8fn2wagkyc9x5csgnm5r1gz34p81" }, "required_statuses": { "type": "array", "items": { "type": "string" }, "description": "The checks and statuses that the run needs to pass.", "example": [ "ci / test" ] }, "required_statuses_source": { "oneOf": [ { "$ref": "#/components/schemas/RequiredStatusesSource", "description": "Where `required_statuses` come from: the configuration file, or the\nprotection of the target branch on the SCM." }, { "type": "null" } ] }, "started_at": { "type": "string", "format": "date-time", "description": "When the run started.", "example": "2026-10-11T09:33:00Z" }, "status": { "$ref": "#/components/schemas/RunStatus", "description": "`assembling` while CIHub builds the test branch, `in_progress` while the\nCI runs; then `succeeded`, `failed`, `timed_out`, `interrupted` when the\nqueue replaced the run, or `cancelled` when a member was cancelled." }, "status_reason": { "$ref": "#/components/schemas/Reason", "description": "Why the run reached its status: a code of the closed vocabulary\n(`specs/DOMAIN.md`)." }, "test_branch": { "type": "string", "description": "The branch that the run tests, which CIHub assembles.", "example": "cihub-merge/pr-118/run_06cx8fn2wtgkyc9x5csgnm5r22ca6g0w" }, "test_sha": { "type": [ "string", "null" ], "description": "The commit that the run tests; `null` while CIHub assembles it.", "example": "e6081b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e" }, "tested_pr_numbers": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "The PRs that the run tests.", "example": [ 118 ] } } }, "RunCheck": { "type": "object", "description": "A check or a status observed on the test SHA of a run.", "required": [ "name", "kind", "required", "status", "observed_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the check concluded, as the CI reports it; `null` before.", "example": "2026-10-11T09:39:00Z" }, "conclusion": { "oneOf": [ { "$ref": "#/components/schemas/CheckConclusion", "description": "The outcome; `null` while the check runs." }, { "type": "null" } ] }, "details_url": { "type": [ "string", "null" ], "description": "The page of the check on the CI.", "example": "https://ci.example.com/acme/web/runs/1234" }, "kind": { "$ref": "#/components/schemas/CheckKind", "description": "`check` for a check with a run, `status` for a commit status." }, "name": { "type": "string", "description": "The name of the check or of the status.", "example": "ci / test" }, "observed_at": { "type": "string", "format": "date-time", "description": "When CIHub saw this report last.", "example": "2026-10-11T09:40:00Z" }, "required": { "type": "boolean", "description": "The run needs it to pass." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the check started, as the CI reports it; `null` before. A commit\nstatus gives the time of its state only.", "example": "2026-10-11T09:31:00Z" }, "status": { "$ref": "#/components/schemas/CheckStatus", "description": "`queued` waits for a runner, `in_progress` runs, `completed` has an\noutcome." } } }, "RunStatus": { "type": "string", "enum": [ "assembling", "in_progress", "succeeded", "failed", "interrupted", "cancelled", "timed_out" ] }, "SettingsSummary": { "type": "object", "description": "The settings of a queue that its page shows, from its last valid\nconfiguration file.", "required": [ "batching_enabled", "batching_size", "batching_max_wait_minutes", "failure_budget_retries", "merge_method" ], "properties": { "batching_enabled": { "type": "boolean", "description": "The queue tests several PRs in one run." }, "batching_max_wait_minutes": { "type": "integer", "format": "int32", "description": "How long a batch that is not full waits for more PRs, in minutes.", "example": 5, "minimum": 0 }, "batching_size": { "type": "integer", "format": "int32", "description": "The most PRs in one batch.", "example": 4, "minimum": 0 }, "enqueue_label": { "type": [ "string", "null" ], "description": "The label that submits a PR when someone adds it; `null` when the\nlabels do not submit (`label_commands.enabled: false`).", "example": "cihub-merge-queue-submit" }, "failure_budget_retries": { "type": "integer", "format": "int32", "description": "How many times a run that fails is tested again before its PRs fail.", "example": 1, "minimum": 0 }, "merge_method": { "$ref": "#/components/schemas/MergeMethod", "description": "How the queue merges a PR into the target branch." } } }, "Setup": { "type": "object", "description": "The setup of a queue: what its last setup read found about the rules of\nthe SCM; no finding means sound rules.", "required": [ "findings" ], "properties": { "checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When CIHub read the setup; `null` before the first read, which comes\nwithin minutes of the creation of the queue.", "example": "2026-10-11T09:00:00Z" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "What the rules miss; empty for sound rules." } } }, "SetupState": { "type": "string", "description": "The verdict of the setup of a repository, computed by the server in this\norder: `started` (the default branch has its queue), `checking` (no read\nyet, or a read asked after the last one), `invalid_config` (the file is\nnot valid), `cannot_merge` (a rule blocks the merges, or the default\nbranch is missing), `ready_with_warnings` (a rule fails without blocking\nthe merges), `ready`.", "enum": [ "started", "checking", "ready", "ready_with_warnings", "cannot_merge", "invalid_config" ] }, "SetupSummary": { "type": "object", "description": "The verdict of the setup of a repository, and when CIHub read it.", "required": [ "state" ], "properties": { "checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When CIHub read the setup; `null` before the first read.", "example": "2026-10-16T09:00:00Z" }, "requested_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When an admin asked to read the setup again, while that read waits;\n`null` otherwise.", "example": "2026-10-16T09:05:00Z" }, "state": { "$ref": "#/components/schemas/SetupState", "description": "The verdict of the setup." } } }, "StateTime": { "type": "object", "description": "The median time in a state of the PRs merged in a period; a PR that did\nnot pass through the state counts as 0.", "required": [ "state", "median_seconds" ], "properties": { "median_seconds": { "type": "integer", "format": "int64", "description": "The median time in the state, in seconds.", "example": 420, "minimum": 0 }, "state": { "$ref": "#/components/schemas/ItemState", "description": "A state before the merge." } } }, "Strategy": { "type": "string", "enum": [ "sequential", "pipelined", "batched", "parallel" ] }, "SubmitPr": { "type": "object", "description": "`POST /orgs/{org}/repos/{repo}/prs/{number}/submit`.", "properties": { "no_batch": { "type": "boolean", "description": "Test the PR alone, never in a batch." }, "priority": { "oneOf": [ { "$ref": "#/components/schemas/PriorityInput", "description": "Without it, the `priority_rules` of the configuration file decide." }, { "type": "null" } ] }, "profile": { "type": [ "string", "null" ], "description": "A profile of the queue of the base branch of the PR; without it, the\n`conditions` of the profiles decide.", "example": "dependencies" } } }, "SubmittedVia": { "type": "string", "enum": [ "comment", "label", "api" ] }, "TimeToMerge": { "type": "object", "description": "The time from the submission of a PR to its merge.", "required": [ "median_seconds", "p90_seconds" ], "properties": { "median_seconds": { "type": "integer", "format": "int64", "description": "Half of the PRs merged within this time, in seconds.", "example": 1380, "minimum": 0 }, "p90_seconds": { "type": "integer", "format": "int64", "description": "90 % of the PRs merged within this time, in seconds.", "example": 2940, "minimum": 0 } } }, "UpdateQueue": { "type": "object", "description": "`PATCH /orgs/{org}/repos/{repo}/queues/{queue}`.", "required": [ "state" ], "properties": { "state": { "$ref": "#/components/schemas/RequestedQueueState", "description": "`running` resumes the queue; `paused` stops its tests and its merges\nand keeps its order; `draining` lets the items in flight merge and\nrefuses new ones." } } }, "User": { "type": "object", "description": "`GET /user`: the person of a session of the dashboard.", "required": [ "login" ], "properties": { "avatar_url": { "type": [ "string", "null" ], "description": "The address of the image of the person on the SCM, `null` when the SCM\ngives none.", "example": "https://avatars.example.com/u/1" }, "login": { "type": "string", "description": "The login of the person on the SCM.", "example": "ada" }, "name": { "type": [ "string", "null" ], "description": "The name that the person gives on the SCM, `null` when they give none.", "example": "Ada Lovelace" }, "synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When CIHub last read from the SCM the repositories that the person\nreaches; `null` until the first read ends, which their lists wait for.", "example": "2026-10-11T09:00:00Z" } } }, "Window": { "type": "object", "description": "The speculation window: how many runs the queue keeps in progress.", "required": [ "current", "floor", "ceiling" ], "properties": { "ceiling": { "type": "integer", "format": "int32", "description": "The largest size of the window.", "example": 8, "minimum": 0 }, "current": { "type": "integer", "format": "int32", "description": "The size of the window now, from `floor` to `ceiling`.", "example": 4, "minimum": 0 }, "floor": { "type": "integer", "format": "int32", "description": "The smallest size of the window.", "example": 1, "minimum": 0 } } } }, "examples": { "csrf_refused": { "summary": "csrf_refused", "value": { "code": "csrf_refused", "detail": "A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.", "status": 403, "title": "Forbidden", "type": "https://cihub.io/docs/api/errors#csrf_refused" } }, "device_code_denied": { "summary": "device_code_denied", "value": { "code": "device_code_denied", "detail": "The person denied the code: the command line is not signed in.", "status": 403, "title": "Forbidden", "type": "https://cihub.io/docs/api/errors#device_code_denied" } }, "device_code_expired": { "summary": "device_code_expired", "value": { "code": "device_code_expired", "detail": "The device code is unknown, already used, or older than 15 minutes: start again.", "status": 400, "title": "Bad Request", "type": "https://cihub.io/docs/api/errors#device_code_expired" } }, "device_code_not_found": { "summary": "device_code_not_found", "value": { "code": "device_code_not_found", "detail": "No sign-in of the command line waits for this code: it is wrong, used, or older than 15 minutes.", "status": 404, "title": "Not Found", "type": "https://cihub.io/docs/api/errors#device_code_not_found" } }, "device_code_pending": { "summary": "device_code_pending", "value": { "code": "device_code_pending", "detail": "The person has not approved or denied the code yet: ask again after `interval` seconds.", "status": 400, "title": "Bad Request", "type": "https://cihub.io/docs/api/errors#device_code_pending" } }, "internal": { "summary": "internal", "value": { "code": "internal", "detail": "The server failed; the logs of the instance say why.", "status": 500, "title": "Internal Server Error", "type": "https://cihub.io/docs/api/errors#internal" } }, "invalid_cursor": { "summary": "invalid_cursor", "value": { "code": "invalid_cursor", "detail": "`from` is not a `cursor` that this list gave.", "status": 400, "title": "Bad Request", "type": "https://cihub.io/docs/api/errors#invalid_cursor" } }, "invalid_request": { "summary": "invalid_request", "value": { "code": "invalid_request", "detail": "The body, the path or the query of the request is not valid.", "status": 400, "title": "Bad Request", "type": "https://cihub.io/docs/api/errors#invalid_request" } }, "item_ended": { "summary": "item_ended", "value": { "code": "item_ended", "detail": "The item of the PR ended: `merged`, `failed` or `cancelled`.", "status": 409, "title": "Conflict", "type": "https://cihub.io/docs/api/errors#item_ended" } }, "item_not_in_test": { "summary": "item_not_in_test", "value": { "code": "item_not_in_test", "detail": "Only an item in `testing` or `pending_failure` can restart its tests.", "status": 409, "title": "Conflict", "type": "https://cihub.io/docs/api/errors#item_not_in_test" } }, "limit_out_of_range": { "summary": "limit_out_of_range", "value": { "code": "limit_out_of_range", "detail": "`limit` is from 1 to 100.", "status": 400, "title": "Bad Request", "type": "https://cihub.io/docs/api/errors#limit_out_of_range" } }, "org_not_found": { "summary": "org_not_found", "value": { "code": "org_not_found", "detail": "No organization has this slug, or the token or the user does not belong to it.", "status": 404, "title": "Not Found", "type": "https://cihub.io/docs/api/errors#org_not_found" } }, "polling_too_fast": { "summary": "polling_too_fast", "value": { "code": "polling_too_fast", "detail": "The command line asked again sooner than `interval`: wait 5 seconds more each time.", "status": 429, "title": "Too Many Requests", "type": "https://cihub.io/docs/api/errors#polling_too_fast" } }, "pr_already_queued": { "summary": "pr_already_queued", "value": { "code": "pr_already_queued", "detail": "The PR is already in a queue of the repository, and its item has not ended.", "status": 409, "title": "Conflict", "type": "https://cihub.io/docs/api/errors#pr_already_queued" } }, "pr_not_found": { "summary": "pr_not_found", "value": { "code": "pr_not_found", "detail": "The PR was never submitted to a queue of the repository.", "status": 404, "title": "Not Found", "type": "https://cihub.io/docs/api/errors#pr_not_found" } }, "queue_not_found": { "summary": "queue_not_found", "value": { "code": "queue_not_found", "detail": "The repository has no queue of this branch.", "status": 404, "title": "Not Found", "type": "https://cihub.io/docs/api/errors#queue_not_found" } }, "rate_limited": { "summary": "rate_limited", "value": { "code": "rate_limited", "detail": "The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.", "status": 429, "title": "Too Many Requests", "type": "https://cihub.io/docs/api/errors#rate_limited" } }, "repo_not_found": { "summary": "repo_not_found", "value": { "code": "repo_not_found", "detail": "The organization has no repository with this name.", "status": 404, "title": "Not Found", "type": "https://cihub.io/docs/api/errors#repo_not_found" } }, "route_not_found": { "summary": "route_not_found", "value": { "code": "route_not_found", "detail": "No route has this path.", "status": 404, "title": "Not Found", "type": "https://cihub.io/docs/api/errors#route_not_found" } }, "run_not_found": { "summary": "run_not_found", "value": { "code": "run_not_found", "detail": "The organization has no run with this identifier.", "status": 404, "title": "Not Found", "type": "https://cihub.io/docs/api/errors#run_not_found" } }, "scm_unavailable": { "summary": "scm_unavailable", "value": { "code": "scm_unavailable", "detail": "The SCM did not answer the check of the access of the person of the session: try again in a moment.", "status": 503, "title": "Service Unavailable", "type": "https://cihub.io/docs/api/errors#scm_unavailable" } }, "scope_missing": { "summary": "scope_missing", "value": { "code": "scope_missing", "detail": "The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.", "status": 403, "title": "Forbidden", "type": "https://cihub.io/docs/api/errors#scope_missing" } }, "sign_in_unavailable": { "summary": "sign_in_unavailable", "value": { "code": "sign_in_unavailable", "detail": "The instance has no public address or no sign-in client: nobody signs in to it.", "status": 503, "title": "Service Unavailable", "type": "https://cihub.io/docs/api/errors#sign_in_unavailable" } }, "too_many_streams": { "summary": "too_many_streams", "value": { "code": "too_many_streams", "detail": "The token or the person already keeps 8 streams open.", "status": 429, "title": "Too Many Requests", "type": "https://cihub.io/docs/api/errors#too_many_streams" } }, "unauthorized": { "summary": "unauthorized", "value": { "code": "unauthorized", "detail": "No API token or session, or one that is unknown or expired.", "status": 401, "title": "Unauthorized", "type": "https://cihub.io/docs/api/errors#unauthorized" } }, "unknown_priority": { "summary": "unknown_priority", "value": { "code": "unknown_priority", "detail": "The name of the priority is not `urgent`, `high`, `medium` or `low`.", "status": 400, "title": "Bad Request", "type": "https://cihub.io/docs/api/errors#unknown_priority" } } }, "securitySchemes": { "session": { "type": "apiKey", "in": "cookie", "name": "__Host-cihub_session" }, "token": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Session", "description": "The person signed in, the sign-in of the command line, and the instance." }, { "name": "Organizations", "description": "An organization is the account of an installation of the App, with its audit log." }, { "name": "Live updates", "description": "The changes of the queues of an organization, as server-sent events." }, { "name": "Queues", "description": "A queue merges the PRs of one target branch, in order, once each one passed its tests on top of those ahead of it." }, { "name": "Pull requests", "description": "A PR in a queue, as its last submission gives it; a PR submitted again gets a new submission, whose history its events keep." }, { "name": "Runs", "description": "A run tests, on the CI, a test branch that holds a group of PRs on top of the PRs ahead of them." }, { "name": "Repositories", "description": "A repository of the organization: what the caller may do on it, and its setup, what CIHub found about the rules of its default branch and its configuration file, with a verdict." } ] }