{
  "openapi": "3.1.0",
  "info": {
    "title": "Merge Pilot REST API",
    "version": "v1",
    "summary": "Change management gate for GitLab and GitHub merge requests.",
    "description": "The Merge Pilot REST API, as served by the backend under `/api/v1`.\n\n**Authentication.** Programs send an API token (`mpt_...`) in\n`Authorization: Bearer <token>`. The web interface uses session cookies\nset when a person signs in; integrations use API tokens.\n\n**Not listed here.** The endpoints of the browser sign-in flow and those\nthat need a signed-in session (security settings, users, API tokens,\nidentity providers, licence) are not in this reference: API tokens cannot\ncall them.\n\n**Envelope.** Every JSON answer is `{\"success\": true, \"data\": ..., \"meta\": ...}`\nor `{\"success\": false, \"error\": {\"message\": \"...\", \"code\": \"...\"}}`.\n`204 No Content` answers have no body.\n\n**Roles.** `platform_admin` (runs the instance, sees every company),\n`company_admin`, `policy_manager`, `auditor` (reads everything of its\ncompany, changes nothing) and `user`. Every role but `platform_admin`\nbelongs to one company and only sees that company. Role gates used below:\n\n| Gate | Roles |\n|---|---|\n| signed in | any role |\n| company admin | `platform_admin`, `company_admin` |\n| policy manager | `platform_admin`, `company_admin`, `policy_manager` |\n| audit reader | `platform_admin`, `company_admin`, `auditor` |\n| directory reader | `platform_admin`, `company_admin`, `policy_manager`, `auditor` |\n| platform admin | `platform_admin` |\n\nThe `auditor` role is read-only everywhere: any non-GET request is\nanswered `403 \"this role can only read\"`, except `POST .../policies/simulate`,\n`POST .../monitoring/report` and `POST /projects/evidence` (they change\nnothing) and the caller's own account: `PUT /auth/me` (profile), changing\nthe own password, unlinking a sign-in provider, making and revoking\npersonal tokens (which act with the auditor's own role), and signing out.\n\n**Company context.** Company members (and their tokens) always act on their\nown company; `company_id` / `X-Company-ID` are ignored for them. A\n`platform_admin` picks the company with the `company_id` query parameter\nor the `X-Company-ID` header on per-company endpoints. Resources of\nanother company answer `404` (so IDs cannot be probed).\n",
    "contact": {
      "name": "CloudNativeWorks"
    }
  },
  "servers": [
    {
      "url": "https://{host}/api/v1",
      "description": "Your Merge Pilot instance",
      "variables": {
        "host": {
          "default": "merge-pilot.example.com",
          "description": "Your Merge Pilot host name"
        }
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Browser sign-in, session refresh and the signed-in account."
    },
    {
      "name": "Merge requests",
      "description": "Merge requests Merge Pilot tracks, their policy decision, approval state and votes."
    },
    {
      "name": "Projects",
      "description": "Repositories registered in Merge Pilot."
    },
    {
      "name": "Change policies",
      "description": "Ordered change policies per VCS connection, templates and simulation."
    },
    {
      "name": "Approver pools",
      "description": "Groups of people who may approve change approvals."
    },
    {
      "name": "Config changes",
      "description": "Four-eyes review of control changes (when the company turned on `governance.config_approval`)."
    },
    {
      "name": "Companies",
      "description": "Company settings (secret values are never returned)."
    },
    {
      "name": "People",
      "description": "The company's people directory."
    },
    {
      "name": "Connections",
      "description": "VCS and tracker connections, their settings, permissions and the GitHub\nApp. Secrets are write-only: answers show `has_*` flags instead.\n"
    },
    {
      "name": "VCS operations",
      "description": "Members, groups, CI/CD variables, branches and branch protection on the\nVCS for the company's registered repositories: what people's own VCS\nrole does not allow. They are done with the connection's account. Merge Pilot does them for people: company admins may use them all; others need the connection's rule for each operation (`vcs_permissions`): it is on, names their Merge Pilot role (`user`, `policy_manager`), and their linked VCS account holds at least its `min_access` on the repository (read with the connection's account; for a group, on one of the company's registered repositories in it; joining has no minimum). Refusals answer 403 in plain words: \"this connection does not let people <operation> through Merge Pilot\", \"your Merge Pilot role cannot <operation> through this connection\", \"this needs at least <role> on this repository in <VCS> (you have <role>)\", \"you have no access to this repository in <VCS>: this needs at least <role> on it\" (GitLab Minimal access, and the read everyone has on a public GitHub repository, are no access). Auditors may only use the GET operations, of rules that are on, whatever their role on the VCS (they change nothing, and variable values are never returned to them). Reading variables serves viewing and changing them: the lists accept `view_variables` or the matching `manage_*` rule. `GET /vcs-ops/projects/{pid}/my-access` says what the caller may do. Every operation is audited with `requested_by`, `rule`, `vcs_access_level` and `acted_as` (`merge-pilot`).\nAn operation the connection's VCS does not have answers 501: on GitHub,\nthe group list, and joining and leaving groups.\nThe VCS's own answers map to: input it does not accept (GitLab 400,\nGitHub 422) → 400 with its message (\"GitLab answered 400: …\"); its API\nrate limit → 429 with `Retry-After`; Merge Pilot's own account refused\n(401: a revoked or expired token, or the App's credentials) → 502\n\"Merge Pilot's account was refused by GitLab; check the connection\";\na missing permission (403) → 403; anything else → 502.\n"
    },
    {
      "name": "Tracker",
      "description": "Merge Pilot's built-in issue tracker (projects, issues, comments)."
    },
    {
      "name": "Audit",
      "description": "Audit log, inbound webhook log and compliance reports."
    },
    {
      "name": "Insights",
      "description": "Dashboard, DORA metrics, cycle time and bottleneck analytics."
    },
    {
      "name": "Delegations",
      "description": "Approval delegations (an approver on leave hands over their votes)."
    },
    {
      "name": "Notification deliveries",
      "description": "Deliveries of the company's notification routes (Slack, Teams, email, webhook) and personal emails, retried and kept 7 days; route tests."
    },
    {
      "name": "Notifications",
      "description": "A person's personal notification emails (preferences) and the public unsubscribe links of those emails."
    },
    {
      "name": "Jobs",
      "description": "Background jobs (processing of merge request events)."
    },
    {
      "name": "Health",
      "description": "Service health and monitored health checks."
    },
    {
      "name": "Platform",
      "description": "Instance-wide settings and the license, for platform admins (browser\nsession only). Any signed-in account may read the public addresses and\nthe license state.\n"
    },
    {
      "name": "Diagnostics",
      "description": "Tracing and replay of merge request processing, and the log of calls\nMerge Pilot made to the VCS and the tracker. Platform admins (the Debug\nand API monitor pages under Insights).\n"
    }
  ],
  "paths": {
    "/auth/me": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "operationId": "getMe",
        "summary": "The signed-in account",
        "description": "Returns the account of the session or personal API token. A service\ntoken acts for no person and is answered `403 \"a service token acts for\nno person: use a personal token or a signed-in session\"`.\n",
        "responses": {
          "200": {
            "description": "The account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/auth/me' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "put": {
        "tags": [
          "Authentication"
        ],
        "operationId": "updateMe",
        "summary": "Change own display name or language",
        "description": "The display name can only be changed on accounts created in Merge Pilot. Auditors may change their own profile too.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "display_name": {
                    "type": "string"
                  },
                  "language": {
                    "type": "string",
                    "description": "Interface language code."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/auth/me' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/auth/me/notification-preferences": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "operationId": "getMyNotificationPreferences",
        "summary": "Own personal notification emails",
        "description": "The event types that can reach the signed-in person by email (as a\nchange approval's assignee or approver, a change's author, a company\nadmin, or about their own account), with their choice. Service tokens\nare refused (403). A platform admin belongs to no company:\n`available` is false and `events` empty.\n",
        "responses": {
          "200": {
            "description": "The choices.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPrefsEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/auth/me/notification-preferences' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "put": {
        "tags": [
          "Notifications"
        ],
        "operationId": "updateMyNotificationPreferences",
        "summary": "Turn personal notification emails on or off",
        "description": "Turns the event types given on (`true`) or off (`false`); the others\nkeep their choice. 400 for an event type that is not sent to this\nperson, or for a platform admin. Audited as\n`notification_preferences_changed`. Answers the choices as GET does.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "events"
                ],
                "properties": {
                  "events": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    },
                    "example": {
                      "mr_blocked": false,
                      "connection_recovered": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The choices.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPrefsEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/auth/me/notification-preferences' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/notifications/unsubscribe": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "operationId": "openUnsubscribeLink",
        "summary": "Open an unsubscribe link (redirect)",
        "description": "Public, no sign-in. Redirects (303) a browser that opened the one-click address to the unsubscribe page of the web app, which shows what the link turns off; a GET changes nothing.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/UnsubscribeToken"
          }
        ],
        "responses": {
          "303": {
            "description": "To the unsubscribe page."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/notifications/unsubscribe' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Notifications"
        ],
        "operationId": "unsubscribe",
        "summary": "Unsubscribe (one click)",
        "description": "Public: the signed token is the credential; no sign-in, cookie or\nCSRF token (RFC 8058: a mail client POSTs `List-Unsubscribe=One-Click`\nwith nothing but the link). Turns the token's event type off for its\nperson in its company, as `PUT /auth/me/notification-preferences`\nwould. A token is valid 90 days and stops working when the server's\nsigning secret changes; 400 when it was changed, has expired, names\nan event that is not sent personally, or its person is gone,\ndeactivated or no longer in the token's company (the same answer,\nrevealing nothing about them). Audited\nas `notification_unsubscribed` (`one_click` true for the mail\nclient's POST). Answers 200, no redirect.\n",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/UnsubscribeToken"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "List-Unsubscribe": {
                    "type": "string",
                    "const": "One-Click"
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "List-Unsubscribe": {
                    "type": "string",
                    "const": "One-Click"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsubscribed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnsubscribeDetailsEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/notifications/unsubscribe' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/notifications/unsubscribe/details": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "operationId": "getUnsubscribeDetails",
        "summary": "What an unsubscribe link turns off",
        "description": "Public. The event type, company and person the token names, and whether the person gets these emails now; changes nothing. 400 as for the POST.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/UnsubscribeToken"
          }
        ],
        "responses": {
          "200": {
            "description": "What the link turns off.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnsubscribeDetailsEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/notifications/unsubscribe/details' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/auth/me/sso": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "operationId": "listMyIdentityProviders",
        "summary": "My identity providers",
        "description": "The company's identity providers the signed-in person can link (enabled\nand allowed by the platform), and those already linked. Empty for a\nplatform admin. A personal API token reads its person's providers; a\nservice token acts for no person and is answered `403 \"a service token\nacts for no person: use a personal token or a signed-in session\"`.\n",
        "responses": {
          "200": {
            "description": "Providers.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/MyIdentityProvider"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/auth/me/sso' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/merge-requests": {
      "get": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "listMergeRequests",
        "summary": "List merge requests",
        "description": "Signed in (any role). Members see their company's merge requests; a\nplatform admin sees all companies unless `company_id` is given.\n\nA listed merge request leaves out its detail lists: the scans'\nfindings (`secret_scan.findings`, `.suppressed`, `.unscanned`;\n`sca_scan.problems`, `.unpinned`, `.unsupported`, `.license_findings`,\n`.package_findings`, `.advisories`, `.sources.findings`,\n`.sources.files_checked`; `workflow_scan.findings`; `image_scan.images`,\n`.unresolved`; `iac_scan.findings`; `signatures.unsigned`;\n`code_owners.sets`), `pipelines`, `changes.files`, `committers` and\n`issue_tracker.change_approval_history`. Their counts and statuses are\nkept; `GET /merge-requests/{id}` returns them all.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "state",
            "in": "query",
            "description": "MR state (`opened`, `merged`, `closed`, `out_of_scope`, ...). `status` is accepted as an alias.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "repo_id",
            "in": "query",
            "description": "VCS repository ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Case-insensitive search in title, source/target branch, author and the repository's path (the merge request's link).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "watched",
            "in": "query",
            "description": "`true`: only merge requests of watched projects; `false`: none of them.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "attention",
            "in": "query",
            "description": "`true`: only open merge requests of change-managed projects that cannot move\nuntil someone acts — refused by policy, a blocking check failed (a failed risk\ncheck is a hold), the approval failed, or an approval is awaited (an emergency\nchange's review, or an open change approval).\n",
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            }
          },
          {
            "name": "change_type",
            "in": "query",
            "description": "Only merge requests whose policy is of this change type.",
            "schema": {
              "type": "string",
              "enum": [
                "standard",
                "normal",
                "emergency"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "name": "sort",
            "in": "query",
            "description": "`title`, `author`, `created_at`, `updated_at` or `risk`; prefix `-` for descending. Default `-created_at`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of merge requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MergeRequestListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/merge-requests' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/merge-requests/fetch": {
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "fetchMergeRequest",
        "summary": "Process a merge request by its number",
        "description": "Queues the merge request with this number for processing, as if its\nwebhook had arrived: for one Merge Pilot never heard of (its webhook\nwas lost, or it was open before its repository was added). Anyone of\nthe company. The repository must be in Merge Pilot (404 otherwise). A\nleading `!` or `#` is accepted. Audited as `mr_fetch_requested`.\nRepositories are also swept for such merge requests now and then\n(`monitoring.open_mr_sweep_hours`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "connection_id",
                  "repo_id",
                  "mr_number"
                ],
                "properties": {
                  "connection_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "repo_id": {
                    "type": "string"
                  },
                  "mr_number": {
                    "type": "string",
                    "example": "!42"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/fetch' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/merge-requests/lookup": {
      "get": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "lookupMergeRequest",
        "summary": "Find a merge request's ID by repository and number",
        "parameters": [
          {
            "name": "repo_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mr_number",
            "in": "query",
            "required": true,
            "description": "The MR/PR number on the VCS (IID on GitLab).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "connection_id",
            "in": "query",
            "description": "VCS connection ID (repository IDs are only unique per VCS connection).",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "The merge request's ID.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "$ref": "#/components/schemas/ObjectId"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/merge-requests/lookup' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/merge-requests/sync-states": {
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "syncMergeRequestStates",
        "summary": "Queue a background re-read of the open merge requests' state from the VCS",
        "description": "Signed in (not auditors). Queues one `mr_state_sync` background job per VCS\nconnection with open merge requests in the company; the job asks the VCS\nfor their state (at most 300 per run, those checked longest ago first,\nyielding the rate limit's share kept for live events) and queues\nclose/merge processing for those closed or merged on the VCS. Answers at\nonce. A connection is skipped while its sync is waiting or running, and\nwhen one was queued within the last 5 minutes (1 minute with `force=true`,\nthe manual sync).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          },
          {
            "name": "force",
            "in": "query",
            "description": "The manual sync, skipped only when one was queued within the last minute.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Per VCS connection, what was done.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "queued": {
                              "type": "integer",
                              "description": "Connections a sync was queued for."
                            },
                            "running": {
                              "type": "integer",
                              "description": "Connections whose sync is already waiting or running."
                            },
                            "recent": {
                              "type": "integer",
                              "description": "Connections synced within the interval (skipped)."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/sync-states' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/merge-requests/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "get": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "getMergeRequest",
        "summary": "Get a merge request with its decision and approval state",
        "description": "Signed in (any role, own company). The answer carries the matched\npolicy (`policy`), the latest evaluation (`decision`: merge gate and\nevery control's result), the change approval (`issue_tracker`), approval groups\nand votes (`approval`), risk assessment and scan summaries.\n",
        "responses": {
          "200": {
            "description": "The merge request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MergeRequestEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/merge-requests/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/merge-requests/{id}/timeline": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "get": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "getMergeRequestTimeline",
        "summary": "Jobs and audit entries of a merge request, newest first",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Timeline entries, newest first (page 1 holds the latest events; later pages are older). `meta` has `total`, `page`, `page_size`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "job",
                                  "audit"
                                ]
                              },
                              "timestamp": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "head_sha": {
                                "type": "string",
                                "description": "The head commit the entry is about, when it names one (a job's result or payload, an audit entry's details). Absent otherwise."
                              },
                              "data": {
                                "type": "object",
                                "description": "The raw job or audit log document.",
                                "additionalProperties": true
                              }
                            }
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/timeline' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/merge-requests/{id}/votes": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "voteOnMergeRequest",
        "summary": "Approve or reject the merge request's change approval",
        "description": "Records the caller's vote on the open change approval: an open merge\nrequest's, or the review of a merged change (an emergency change, or a\nlate decision on an unapproved merge) while it is undecided. The caller must be a\nperson (a browser session or a **personal** token; a service token\nhas no account and the vote fails), must have linked an account on the\nMR's VCS (My profile), must not be the author, and must be eligible\nunder the policy's approval groups (directly, or as an active delegate\nof an approver). Separation of duties restricts approving only: a\ncommitter the policy does not let approve may still reject. The\ncompany's \"only the assignee decides\" setting applies to tracker\ndecisions, not to votes. Not allowed for auditors. 409 when the\ncompany decides Jira change approvals in Jira only\n(`tracker_decisions_only`) and this one is in Jira.\n\nWhen the votes reach a group's quorum, or the rejections reject it\nunder the policy's `rejection_mode` (one rejection by default), the change approval is\nmoved to the tracker's approved/rejected status and the MR is evaluated\nagain. A rejection that does not reject yet is recorded and commented\non the change approval. The decision is recorded as one made in the tracker is: the\n`mr_approved` or `change_approval_rejected` audit entry, the\nnotification and a comment on the merge request (a merged change's\nreview also writes `change_approval_decided_after_mr_merged`).\nAnswers the reloaded merge request.\n\nErrors: `400` bad decision, or a reject whose comment is shorter than\n5 characters (trimmed); `403` no linked VCS account, author, not an\napprover, committer approving under a blocking separation of duties;\n`409` no change approval to vote on, merge request closed, change\napproval already decided or approved, standard change (pre-approved),\nchange approval changed concurrently.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "decision"
                ],
                "properties": {
                  "decision": {
                    "type": "string",
                    "enum": [
                      "approve",
                      "reject"
                    ]
                  },
                  "comment": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Why the change is rejected; required when rejecting, 5 characters at least (trimmed)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The merge request after the vote.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MergeRequestEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "503": {
            "description": "Whether the company decides change approvals in the tracker only could not be read: try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/votes' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/merge-requests/{id}/rejection/withdraw": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "withdrawRejection",
        "summary": "Withdraw a rejection of the change approval",
        "description": "Removes `voter`'s rejection (default: the caller's own) from the open\nmerge request's current change approval, and decides it again from the\nremaining votes: open, approved, or still rejected by others. The\ntracker follows (the connection's reopen status when open again, its\napproved state when approved) and gets a comment. Allowed for whoever\ncast the rejection (or stood in for its voter) and company\nadministrators, unless the policy sets `no_withdraw`. Audited as\n`change_approval_rejection_withdrawn`. Answers the reloaded merge request.\n409 when the company decides Jira change approvals in Jira only\n(`tracker_decisions_only`) and this one is in Jira.\n\nErrors: `400` reason shorter than 5 characters; `403` someone else's\nrejection, or the policy forbids withdrawals; `404` the voter has no\nrejection on the change approval; `409` no change approval, the merge\nrequest is not open or is watched, or the change approval changed meanwhile.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "voter": {
                    "type": "string",
                    "description": "Who rejected, as the vote names them; default: the caller."
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 5,
                    "description": "Why it is withdrawn (goes to the audit log and the tracker)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The merge request after the withdrawal.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MergeRequestEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "503": {
            "description": "Whether the company decides change approvals in the tracker only could not be read: try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/rejection/withdraw' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/merge-requests/{id}/freeze-release": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "releaseFromFreeze",
        "summary": "Let one held change go ahead during a change freeze",
        "description": "Releases the open merge request from the change freeze that holds it\nnow, for the commit `head_sha` (a newer commit needs a new release).\nOnly when its policy sets `controls.freeze.release`; allowed for\nmembers of `controls.freeze.release_pool_id` (else the policy's\napprover pools, else company admins), never the author. The caller must\nbe a person with a linked VCS account. A merge after the release is not\nflagged as merged in the freeze. Audited as `freeze_release`.\n\nThe release is for that commit only: a merge of a later commit is\nflagged as merged in the freeze. Freezes are told apart by name (the\ncompany's freeze names are unique).\n\nErrors: `400` reason shorter than 10 characters or no `head_sha`;\n`403` the policy allows no releases, author, not allowed; `409` the\nmerge request is not open, no freeze holds it now, or `head_sha` is\nnot its head (`the merge request has a newer commit (…)`: an earlier\nrelease stays as it was).\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason",
                  "head_sha"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 10,
                    "description": "Justification (goes to the audit trail)."
                  },
                  "head_sha": {
                    "type": "string",
                    "description": "The commit let go ahead."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Released.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        },
                        "freeze": {
                          "type": "string",
                          "description": "The freeze's name."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/freeze-release' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/merge-requests/{id}/risk-allow": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "liftRiskHold",
        "summary": "Accept the risk of a risk-blocked merge request",
        "description": "Lifts a risk hold for the assessed head commit. Allowed for members of\nthe policy's release pool (or its approval pool), or company admins when\nthe policy names none; never the author. The caller must be a person\nwith a linked VCS account. Not allowed for auditors.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 10,
                    "description": "Justification (goes to the audit trail)."
                  },
                  "head_sha": {
                    "type": "string",
                    "description": "The commit whose risk the caller accepts."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Message"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/risk-allow' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/merge-requests/{id}/rescan": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "rescanMergeRequest",
        "summary": "Run a scan of the merge request again",
        "description": "Any role but auditor (merge requests of the caller's company). Runs the scan of\nthe merge request's head again: `secret` (secret scan), `sca` (the\ndependency scan, which also checks licenses, package health and\ndependency sources), `workflow` (the CI configuration check, on GitHub\nand GitLab), `image` (the container image scan) or `iac` (the\ninfrastructure check). `workflow`, `image` and `iac` answer 400 when the\nmerge request's policy does not run that check. 409 when the merge request is\nnot open (a merged or closed merge request's scans stay as recorded), or\nthe repository is watched and scans are off for watched repositories.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "scan"
                ],
                "properties": {
                  "scan": {
                    "type": "string",
                    "enum": [
                      "secret",
                      "sca",
                      "workflow",
                      "image",
                      "iac"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "`{\"message\": \"rescan started\", \"job_id\": \"...\"}` or `{\"message\": \"scan already in progress\"}`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "job_id": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The merge request is not open",
            "or the repository is watched and scans are off for watched repositories.": null
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/rescan' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/merge-requests/{id}/resync": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "resyncMergeRequest",
        "summary": "Re-read CI and change approval state and process the merge request again",
        "description": "For when a webhook was lost. Open merge requests are reconciled and processed again; a merged or closed one only gets the tracker moves it is owed, its record is not changed (409 when it owes none). Superseded change approvals owed a move to the cancelled status are moved too. 502 when the VCS/tracker call fails.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "`{\"message\": \"Resync started\", \"actions\": [...]}`",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "actions": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/resync' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/merge-requests/{id}/assign-me": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "assignMeToChangeApproval",
        "summary": "Take the change approval",
        "description": "The caller becomes the assignee of the merge request's open change approval in the\nlinked tracker (built-in or Jira). They must be someone who may take it:\nholding one of the approver roles (the pool's, the project's or the\nconnection's, exactly), never the change's author, nor a committer when\nthe policy blocks committers; a stand-in holds the role themselves and\nnever sits in the author's seat. A change approval assigned to someone else is taken\nover (commented on the change approval, audited as `change_approval_taken_over`, announced as\n`change_approval_reassigned`). A decided change approval is not taken (409).\n",
        "parameters": [],
        "responses": {
          "200": {
            "description": "`{\"assignee\": \"<tracker account>\"}`",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "assignee": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/assign-me' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/merge-requests/{id}/work-items/{key}/reset-usage": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        },
        {
          "name": "key",
          "in": "path",
          "required": true,
          "description": "Work item key referenced by the MR (e.g. `PROJ-12`).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Merge requests"
        ],
        "operationId": "resetWorkItemUsage",
        "summary": "Restart a work item's usage count",
        "description": "Company admin (checked in the handler). Merged MRs so far no longer count toward the policy's `max_usage` limit.",
        "parameters": [],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Message"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/merge-requests/{id}/work-items/{key}/reset-usage' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "listProjects",
        "summary": "List registered projects",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "description": "gated or monitor (watched).",
            "schema": {
              "type": "string",
              "enum": [
                "gated",
                "monitor"
              ]
            }
          },
          {
            "name": "vcs_connection_id",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of projects.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Project"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/search": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "searchVCSProjects",
        "summary": "Search the connection's VCS for repositories to put under change management",
        "description": "Company admins and platform admins, and people the connection's\n`cm_setup` rule allows (403 otherwise; auditors never). Asks the VCS for at most 20 repositories\nMerge Pilot can set up whose name matches `name`, through the\ncompany's default VCS connection or `connection_id`: on GitLab the\nprojects (not archived) its account holds Maintainer or Owner on,\nmatched by name, path or group (never other public or internal\nprojects of the instance); on GitHub the repositories the App is\ninstalled on, matched by owner and name. Company admins see all of them; others only those where they hold the minimum role of the connection's `cm_setup` rule (checked with their linked VCS account - 400 when they have not linked it). 404 when the\ncompany or connection is not found, 501 when the connection's VCS\ncannot search, 502 when the VCS search fails.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          },
          {
            "name": "name",
            "in": "query",
            "description": "Part of the repository name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "connection_id",
            "in": "query",
            "description": "VCS connection ID (default: the company's default VCS connection).",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The matching repositories.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VCSProject"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/search' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/by-repo-id/{repo_id}": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getProjectByRepoId",
        "summary": "Get a project by VCS repository ID",
        "description": "Answers `data: null` (200) when the repository is not registered.",
        "parameters": [
          {
            "name": "repo_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "connection_id",
            "in": "query",
            "description": "VCS connection ID.",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "The project, or null.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/by-repo-id/{repo_id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getProject",
        "summary": "Get a project",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "The project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/summary": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "projectSummary",
        "summary": "How many projects the filters match, per connection and mode",
        "description": "Counted by the database, however many: what choosing all of them would move. A bulk operation with `select_all` and `q` then takes them (found when it runs).",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "gated",
                "monitor"
              ]
            }
          },
          {
            "name": "vcs_connection_id",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One entry per connection with matches.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "vcs_connection_id": {
                                "$ref": "#/components/schemas/ObjectId"
                              },
                              "watched": {
                                "type": "integer"
                              },
                              "gated": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/summary' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/cm-setup": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "setupChangeManagement",
        "summary": "Put a repository under change management, or set it up again",
        "description": "Company admin, or someone the connection's `cm_setup` rule lets (their\nMerge Pilot role, and its minimum role on the repository through their\nlinked VCS account; 403 with the reason otherwise). The setup steps (`GET /connections/{id}/cm-steps`) are\nwritten; `steps` turns optional ones off or on (missing: the\nconnection's defaults) and `consent` agrees to them, required for a new\nrepository or new steps. Setting a gated repository up again without\nsteps writes those agreed before. A required step the VCS refuses\nchanges nothing (422): what the run created is removed. Audited as\n`cm_setup` with `requested_by`, `rule` (`company admin`, or the\noperation, roles and `min_access`), `vcs_access_level` and `acted_as`\n(`merge-pilot`), as every VCS operation. The company is the caller's\n(platform admins: `company_id` query or `X-Company-ID`). A connection\nturned off answers 409. A repository can be under change management\nthrough one connection only: one that another connection (of any\ncompany) to the same VCS instance has under change management answers\n409 `the repository is under change management through another\nconnection`; it can still be watched through this one, and each\nconnection's webhook is its own.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "repo_id"
                ],
                "properties": {
                  "repo_id": {
                    "type": "string",
                    "description": "The repository's ID on the VCS."
                  },
                  "connection_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "steps": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    }
                  },
                  "consent": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "The repository is watched (move it with its mode); it is under change management through another connection; it is being set up right now (`change management of this repository is being set up right now: try again in a moment`); or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "422": {
            "description": "A required setup step failed; nothing was changed."
          },
          "502": {
            "description": "The caller's access on the VCS could not be verified."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/cm-setup' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/cm-remove": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "removeChangeManagement",
        "summary": "Take a repository out of change management",
        "description": "Company admin, or someone the connection's `cm_remove` rule lets\n(their Merge Pilot role, and its minimum role on the repository\nthrough their linked VCS account; 403 with the reason otherwise). The repository must be registered\nin Merge Pilot for the company (404 otherwise) and gated: a watched one\nanswers 409 (stop watching it with `POST /projects/{id}/unwatch`). What\nthe setup wrote to the repository is removed: Merge Pilot's approval\nrules (GitLab: those named `Merge Pilot — <branch>`, never another\nrule) or ruleset first, then its webhook; branch protection stays.\nWith `undo_setup`, what change management created is also taken back\n(GitLab: the branch protections and the bot membership it added, and\nthe approval settings it changed, to their earlier values; what was\nthere before stays; see `cm_setup.created`). The approval settings go\nback first: when GitLab refuses that, nothing is removed. When the VCS\nkeeps a rule or the webhook (it refuses the deletion, or Merge Pilot's\naccount can no longer read the approval rules because it lost\nMaintainer) the removal fails with what is left and the repository\nstays under change management. Once the gate is gone, a branch\nprotection or the bot membership the VCS refuses to remove does not\nfail it: the repository is removed and `left_on_vcs` names what to\nremove on the VCS by hand. A repository the VCS no longer answers\nfor is taken out with `POST /projects/{id}/forget`. The company is the\ncaller's (platform admins: `company_id` query or `X-Company-ID`).\nAudited as `cm_remove`, with `requested_by`, `rule`,\n`vcs_access_level` and `acted_as` as `cm_setup`. The access people got\non the repository by joining through Merge Pilot, and the tokens it\ncreated there, are released (`project_removed`, audited as\n`vcs_access_grants_released` and `vcs_issued_tokens_released`). A\nconnection turned off answers 409.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "repo_id"
                ],
                "properties": {
                  "repo_id": {
                    "type": "string",
                    "description": "The repository's ID on the VCS."
                  },
                  "connection_id": {
                    "$ref": "#/components/schemas/ObjectId",
                    "description": "Default: the company's default VCS connection."
                  },
                  "undo_setup": {
                    "type": "boolean",
                    "description": "Also take back what change management created on the repository (default false: it stays)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Removed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "removed": {
                              "type": "boolean",
                              "const": true
                            },
                            "left_on_vcs": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "With `undo_setup`, what the VCS refused to take back (a branch protection, the bot membership), with its answer. Empty when everything went."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The repository is watched (stop watching it from its page); or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "500": {
            "description": "Removing what the setup wrote failed (\"cm remove failed: …\", with the VCS's words)."
          },
          "502": {
            "description": "The caller's access on the VCS could not be verified."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/cm-remove' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/cm-status": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getChangeManagementStatus",
        "summary": "Whether each agreed setup step is in place, read live from the VCS",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "repo_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "connection_id",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The live setup.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/CMSetup"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/cm-status' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/bulk": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "startBulkOperation",
        "summary": "Start a bulk operation on a connection's repositories",
        "description": "Runs in the background, a few repositories at a time,\nand answers at once (202). `watch` and `add_gated` take `repos`\n(repositories not in Merge Pilot yet; `add_gated` puts them straight\nunder change management, without watching first); `to_gated`,\n`to_watching` and `unwatch` take `project_ids`. Company admins may run\nany; others need the connection's `cm_setup` rule (watch, add_gated, to_gated) or `cm_remove` rule (to_watching, unwatch) to name their Merge Pilot role, and each repository is checked against the rule's minimum role on it when it runs (one below it fails with the reason). `to_gated` and `add_gated` need `consent` to the setup steps. `select_all` with `q` takes every\nrepository matching `q`, found when the operation starts (its `total`\nis 0 until then; `error` says why it did nothing): for watch and\nadd_gated the connection's repositories whose path contains it and that\nare not in Merge Pilot yet; for the others the connection's projects\nwhose name or path contains it, in the mode the kind moves from. At most 10,000 repositories; one already\nin another running operation is skipped. A person runs at most a\nfew (by default 3) operations at once in a company (409 beyond). The creator's membership and role are checked\nagain as it runs; if they lose access it stops (`failed`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "watch",
                      "add_gated",
                      "to_gated",
                      "to_watching",
                      "unwatch"
                    ]
                  },
                  "vcs_connection_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "repos": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "repo_id": {
                          "type": "string"
                        },
                        "path": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "select_all": {
                    "type": "boolean",
                    "description": "Every repository matching q (see above), instead of repos or project_ids."
                  },
                  "q": {
                    "type": "string"
                  },
                  "project_ids": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ObjectId"
                    }
                  },
                  "steps": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    }
                  },
                  "gate_open": {
                    "type": "boolean",
                    "description": "to_gated: also gate the open merge requests."
                  },
                  "undo_setup": {
                    "type": "boolean",
                    "description": "to_watching and unwatch: also take back what change management created on each repository (what the VCS refuses is a warning on the item)."
                  },
                  "target_branches": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "watch: the projects' own target branches."
                  },
                  "consent": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The operation, queued.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BulkOperation"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "The person already runs as many operations as allowed at once in this company."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/bulk' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      },
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "listBulkOperations",
        "summary": "The company's recent bulk operations",
        "description": "Company admins and auditors see every one, others their own. Finished ones are listed for a week.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "active",
            "in": "query",
            "description": "true: only running ones.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The operations, newest first; has_more when older ones follow.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "items": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/BulkOperation"
                              }
                            },
                            "has_more": {
                              "type": "boolean"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/bulk' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/bulk/{op}": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getBulkOperation",
        "summary": "A bulk operation and a page of its repositories",
        "parameters": [
          {
            "name": "op",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "running",
                "done",
                "failed",
                "skipped",
                "cancelled"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "The operation and its repositories.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "operation": {
                              "$ref": "#/components/schemas/BulkOperation"
                            },
                            "items": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "repo_id": {
                                    "type": "string"
                                  },
                                  "project_id": {
                                    "$ref": "#/components/schemas/ObjectId"
                                  },
                                  "path": {
                                    "type": "string"
                                  },
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "pending",
                                      "running",
                                      "done",
                                      "failed",
                                      "skipped",
                                      "cancelled"
                                    ]
                                  },
                                  "error": {
                                    "type": "string"
                                  },
                                  "warnings": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  }
                                }
                              }
                            },
                            "total": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/bulk/{op}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/bulk/{op}/cancel": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "cancelBulkOperation",
        "summary": "Cancel a bulk operation",
        "description": "Its creator or a company admin. No new repository is started; one being worked on finishes; done ones stay.",
        "parameters": [
          {
            "name": "op",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The operation",
            "cancelling.": null
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The operation is not running."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/bulk/{op}/cancel' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/bulk/{op}/retry-failed": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "retryBulkOperation",
        "summary": "Start an operation over another's failed repositories",
        "parameters": [
          {
            "name": "op",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "The new operation."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "description": "The operation is still running."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/bulk/{op}/retry-failed' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/bulk/{op}/revert-done": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "revertBulkOperation",
        "summary": "Move another operation's done repositories back",
        "description": "to_gated and add_gated become to_watching, watch becomes unwatch.",
        "parameters": [
          {
            "name": "op",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "The new operation."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "description": "The operation is still running."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/bulk/{op}/revert-done' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/watchable": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "listWatchableRepositories",
        "summary": "List the repositories a connection can watch",
        "description": "GitLab: projects the token maintains; GitHub: repositories the App installations cover. A page at a time, searched on the server by path (GitLab searches itself; GitHub repositories are read once and kept for two minutes). Each comes with its project when it is in Merge Pilot already. Others than company admins see only the repositories of the page they maintain.",
        "parameters": [
          {
            "name": "company_id",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "connection_id",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Part of the repository path."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of the repositories.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "has_more": {
                              "type": "boolean"
                            },
                            "items": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "path_with_namespace": {
                                    "type": "string"
                                  },
                                  "web_url": {
                                    "type": "string"
                                  },
                                  "project_id": {
                                    "$ref": "#/components/schemas/ObjectId"
                                  },
                                  "mode": {
                                    "type": "string",
                                    "enum": [
                                      "gated",
                                      "monitor"
                                    ]
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/watchable' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/mode": {
      "put": {
        "tags": [
          "Projects"
        ],
        "operationId": "setProjectMode",
        "summary": "Move a project between watching and change management",
        "description": "Company admin, or someone the connection's rule lets (`cm_setup` to\n`gated`, `cm_remove` to `monitor`), with its minimum role on the\nrepository. To `gated`: the merge gate is set up (as CM setup); with\n`gate_open` the open merge requests are evaluated again and gated now,\notherwise they stay watched until their next commit. To `monitor`: the\ngate rule or ruleset is removed (GitLab branch protection stays, unless\n`undo_setup` takes back what change management created) and only\nevent delivery is kept.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "mode"
                ],
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "gated",
                      "monitor"
                    ]
                  },
                  "gate_open": {
                    "type": "boolean"
                  },
                  "undo_setup": {
                    "type": "boolean",
                    "description": "To monitor: also take back what change management created (default false)."
                  },
                  "steps": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    },
                    "description": "To gated: the setup steps (missing: the connection's defaults)."
                  },
                  "consent": {
                    "type": "boolean",
                    "description": "To gated - agrees to the setup steps (required)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/projects/{id}/mode' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/{id}/branches": {
      "put": {
        "tags": [
          "Projects"
        ],
        "operationId": "setProjectBranches",
        "summary": "Set the project's target and excluded branches",
        "description": "Company admin, or someone the connection's `cm_setup` rule lets\n(gating fewer branches: the `cm_remove` rule), with its minimum role\non the repository. Target branches replace the company's branch patterns\n(empty - the company's); merge requests into an excluded branch are not\nfollowed. A gated project's gate is set up again for them; when that\nfails nothing changes.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "target_branches": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Glob patterns."
                  },
                  "excluded_branches": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Glob patterns."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/projects/{id}/branches' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/{id}/push-ignore": {
      "put": {
        "tags": [
          "Projects"
        ],
        "operationId": "setProjectPushIgnore",
        "summary": "Set the logins whose pushes to the project are not recorded",
        "description": "Company admin. Adds to the company's direct_changes.ignore_list.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "logins": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Login globs."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/projects/{id}/push-ignore' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/{id}/unwatch": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "unwatchProject",
        "summary": "Stop watching a project",
        "description": "Company admin, or someone the connection's `cm_remove` rule lets, with its minimum role on the repository. The event delivery is removed and the project deleted; its recorded merge requests stay. 409 for a project under change management. A webhook the VCS keeps fails the request (502) and the project stays. With `undo_setup`, what change management created while it gated the repository and left in place when switched to watching (`cm_setup.created`) is taken back too, as for `POST /projects/cm-remove`; what the VCS refuses is listed in `left_on_vcs` and does not fail the request.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "undo_setup": {
                    "type": "boolean",
                    "description": "Also take back what change management created (default false: it stays)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "No longer watched.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "left_on_vcs": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "With `undo_setup`, what the VCS refused to take back, with its answer."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/{id}/unwatch' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/{id}/forget": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "forgetProject",
        "summary": "Take a repository out of Merge Pilot without touching the VCS",
        "description": "Company admin. For a repository the VCS no longer answers for (deleted,\nmoved, the GitHub App's access to it removed, the token revoked), which\ncannot be removed the usual way. Nothing is changed on the VCS: the\nproject is deleted, its open merge requests are no longer followed,\naccess people got through Merge Pilot is released, and the answer\nlists what Merge Pilot's records say it set up there (approval rules or\nruleset, branch protection, membership, approval settings, webhook), to\nremove by hand. A `reason` is required. Audited as `project_forgotten`\nwith the reason and that list. The connection can be deleted once no\nrepository is registered through it. A repository the VCS still\nanswers for (and not marked as lost) is refused with 409: it is\nremoved the usual way, so its gate does not stay behind.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "reason"
                ],
                "properties": {
                  "reason": {
                    "type": "string",
                    "description": "Why the repository cannot be removed the usual way."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Removed from Merge Pilot.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "left_on_vcs": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "What Merge Pilot had set up on the VCS",
                              "to remove there by hand.": null
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The VCS still answers for the repository (`the VCS still answers for this repository: …`)."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/{id}/forget' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/{id}/import-history": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "importProjectHistory",
        "summary": "Import a watched project's past merge requests again",
        "description": "Company admin, or someone the connection's `cm_setup` rule lets, with\nits minimum role on the repository. Queues the import of the company's\nhistory window (`monitoring.backfill_days`) in the background; merge\nrequests imported before are judged again with the current policies,\nthose recorded live are skipped. While an import is pending or\nrunning the project is answered unchanged. 409 when the project is not\nwatched or the company imports no history (`monitoring.backfill_days`\nis 0, the default); 503 when the import could\nnot be queued (the project's import is then marked failed). Audited as\n`project_history_imported` (`failure` when it could not be queued).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "The project, with its `backfill` status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "503": {
            "description": "The import could not be queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/{id}/import-history' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/mode-impact": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getModeImpact",
        "summary": "The open merge requests and what change management would decide for them",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "The open merge requests.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "$ref": "#/components/schemas/ObjectId"
                              },
                              "mr_number": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "policy": {
                                "type": "string"
                              },
                              "gate": {
                                "type": "string",
                                "enum": [
                                  "approved",
                                  "pending",
                                  "blocked"
                                ]
                              },
                              "needs_change_approval": {
                                "type": "boolean"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/{id}/mode-impact' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vulnerabilities": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "listVulnerabilities",
        "summary": "The vulnerability inventory of the company's default branches",
        "description": "Company admins, policy managers and auditors. One finding per advisory\nand package version on a project's default branch, from when it was\nfirst seen until it is fixed; filtered, sorted and paged on the server.\nThe packages of the container images the branch refers to are here too:\ntheir ecosystem is `image/` and the package type (`image/alpine`,\n`image/debian`, `image/python-pkg`, ...) and their manifests are the\nimages. They are scanned again with each analysis and each advisory\ncheck, and fixed when the branch no longer refers to the image or the\nimage no longer has the package version.\n",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "excepted",
                "fixed",
                "all"
              ],
              "default": "open"
            },
            "description": "`open`: open without an exception; `excepted`: open with one."
          },
          {
            "name": "severity",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "critical",
                "high",
                "medium",
                "low"
              ]
            },
            "description": "Minimum severity."
          },
          {
            "name": "project_id",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "ecosystem",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "images",
                "dependencies"
              ]
            },
            "description": "`images`: the container images' findings; `dependencies`: the dependency manifests'. Ignored with `ecosystem`."
          },
          {
            "name": "manifest",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Manifest path prefix."
          },
          {
            "name": "scope",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "runtime",
                "dev"
              ]
            }
          },
          {
            "name": "direct",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_fix",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "malicious",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "kev",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Exploited in the wild (CISA KEV)."
          },
          {
            "name": "introduced_by",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            },
            "description": "The merge request that brought it in."
          },
          {
            "name": "from_merge",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Only findings a merge request brought in."
          },
          {
            "name": "new",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Only findings that were new when first seen: leaves out the baseline of each project's first analysis."
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "analysis",
                "merge",
                "advisory",
                "direct"
              ]
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "First seen at or after."
          },
          {
            "name": "until",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "First seen before."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Package name prefix",
            "or an advisory ID or alias (any case).": null
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`severity`, `advisory`, `package`, `project`, `fixed_in`, `fixed_at`, `first_seen` or `epss`; prefix `-` for descending. Default `-severity`."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of findings.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VulnFinding"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/vulnerabilities' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vulnerabilities/feeds": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getVulnerabilityFeeds",
        "summary": "When the CISA KEV and FIRST EPSS feeds were last read",
        "description": "Company admins, policy managers and auditors. `enabled` is false when this Merge Pilot does not read them.",
        "responses": {
          "200": {
            "description": "The feeds' state.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "enabled": {
                              "type": "boolean"
                            },
                            "status": {
                              "type": "object",
                              "properties": {
                                "kev_refreshed_at": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "kev_version": {
                                  "type": "string"
                                },
                                "kev_error": {
                                  "type": "string",
                                  "description": "Why the last read failed (its earlier data is kept)."
                                },
                                "epss_refreshed_at": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "epss_score_date": {
                                  "type": "string"
                                },
                                "epss_error": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/vulnerabilities/feeds' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vulnerabilities/summary": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "project_id",
          "in": "query",
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        },
        {
          "name": "kind",
          "in": "query",
          "schema": {
            "type": "string",
            "enum": [
              "images",
              "dependencies"
            ]
          },
          "description": "Only the container images' findings, or only the dependency manifests'."
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getVulnerabilitySummary",
        "summary": "The inventory at a glance",
        "description": "Company admins, policy managers and auditors.",
        "responses": {
          "200": {
            "description": "Counts.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VulnSummary"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/vulnerabilities/summary' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vulnerabilities.csv": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "exportVulnerabilities",
        "summary": "The filtered inventory as CSV",
        "description": "The list's filters apply (no paging; at most 20,000 rows). Text that a spreadsheet would read as a formula is prefixed with `'`.",
        "responses": {
          "200": {
            "description": "CSV.",
            "headers": {
              "X-Export-Truncated": {
                "description": "`true` when more rows match than the file holds: narrow the filters to export the rest.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Export-Limit": {
                "description": "The row limit the file stopped at (sent with `X-Export-Truncated`).",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/vulnerabilities.csv' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/direct-changes": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "listDirectChanges",
        "summary": "Changes made to watched branches without a merge request",
        "description": "Company admins, policy managers and auditors. Direct pushes, force\npushes and deleted branches on the target branches and default\nbranches, found by push events or the head check; filtered, sorted and\npaged on the server.\n",
        "parameters": [
          {
            "name": "project_id",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "class",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "direct",
                "mixed",
                "ignored"
              ]
            },
            "description": "`mixed`: some of its commits came through merge requests."
          },
          {
            "name": "violation",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "To a project under change management."
          },
          {
            "name": "would_have_blocked",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "To a watched project."
          },
          {
            "name": "forced",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "deleted",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "via",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "push",
                "head_check"
              ]
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "until",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Project",
            "pusher": null,
            "commit SHA": null,
            "title or author.": null
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`detected_at`, `project`, `branch` or `commits`; prefix `-` for descending. Default `-detected_at`."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of direct changes.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/DirectChange"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/direct-changes' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/direct-changes/summary": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "project_id",
          "in": "query",
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getDirectChangeSummary",
        "summary": "The last 30 days' direct changes at a glance",
        "description": "Company admins, policy managers and auditors.",
        "responses": {
          "200": {
            "description": "Counts.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DirectChangeSummary"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/direct-changes/summary' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/direct-changes.csv": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "exportDirectChanges",
        "summary": "The filtered direct changes as CSV",
        "description": "The list's filters apply (no paging; at most 20,000 rows). Text that a spreadsheet would read as a formula is prefixed with `'`.",
        "responses": {
          "200": {
            "description": "CSV.",
            "headers": {
              "X-Export-Truncated": {
                "description": "`true` when more rows match than the file holds: narrow the filters to export the rest.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Export-Limit": {
                "description": "The row limit the file stopped at (sent with `X-Export-Truncated`).",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/direct-changes.csv' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/iac-findings": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "listIaCFindings",
        "summary": "The infrastructure findings of the company's default branches",
        "description": "Company admins, policy managers and auditors. One finding per\nmisconfiguration in a project's default branch's infrastructure files\n(Terraform, Kubernetes, Helm charts rendered with their values,\nDockerfiles, CloudFormation), from when it was first seen until it is\nfixed. Each project analysis checks the files that changed since the\nlast one (a Terraform directory and a Helm chart whole); the company's\nskipped checks and paths are left out.\n",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "fixed",
                "all"
              ],
              "default": "open"
            }
          },
          {
            "name": "severity",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "critical",
                "high",
                "medium",
                "low"
              ]
            },
            "description": "Minimum severity."
          },
          {
            "name": "project_id",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A file path prefix or a check ID (`KSV-0017`)."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "severity",
                "project",
                "file",
                "check",
                "first_seen_at",
                "fixed_at"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "Findings, worst first by default.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/IaCFindingRecord"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/iac-findings' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/iac-findings/summary": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "project_id",
          "in": "query",
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getIaCFindingSummary",
        "summary": "The infrastructure inventory at a glance",
        "description": "Company admins, policy managers and auditors.",
        "responses": {
          "200": {
            "description": "Counts.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "integer"
                              },
                              "description": "Open findings by severity (critical, high, medium, low, unknown)."
                            },
                            "open_total": {
                              "type": "integer"
                            },
                            "fixed_30_days": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/iac-findings/summary' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vulnerability-exceptions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "listVulnerabilityExceptions",
        "summary": "The company's vulnerability exceptions",
        "description": "Company admins, policy managers and auditors.",
        "parameters": [
          {
            "name": "active",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "true: in force; false: revoked or expired."
          }
        ],
        "responses": {
          "200": {
            "description": "Newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VulnException"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/vulnerability-exceptions' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Insights"
        ],
        "operationId": "createVulnerabilityException",
        "summary": "Accept an advisory, or mark it not affecting",
        "description": "Company admins and policy managers. Until it expires, merge requests\nintroducing the advisory are not held for it and findings show it.\n`expires_at` may be at most the end of the day (23:59:59.999) that is\nthe company's `vulnerabilities.exception_max_days` from today, in the\ncompany's time zone (UTC when it has none); a later one is refused\n(400) with the latest allowed day. With four-eyes review on, it waits\nfor a second person (202).\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VulnExceptionInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Granted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VulnException"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "202": {
            "description": "Waiting for review: `{\"pending\": true, \"change\": {...}}`."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/vulnerability-exceptions' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/vulnerability-exceptions/{eid}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "eid",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "delete": {
        "tags": [
          "Insights"
        ],
        "operationId": "revokeVulnerabilityException",
        "summary": "Revoke an exception",
        "description": "Company admins and policy managers; with four-eyes review on, it waits for a second person (202). The merge requests it let through are evaluated again.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Revoked."
          },
          "202": {
            "description": "Waiting for review."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "No such exception, or it already ended (revoked or expired): nothing is revoked or audited."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/companies/{id}/vulnerability-exceptions/{eid}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/sca-exclude": {
      "put": {
        "tags": [
          "Projects"
        ],
        "operationId": "updateProjectSCAExclude",
        "summary": "Set the manifest paths the project's analysis skips",
        "description": "Company admin. Glob patterns (test fixtures, examples), on top of the company's blocked paths; an empty list removes them.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/projects/{id}/sca-exclude' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/{id}/analysis": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getLatestProjectAnalysis",
        "summary": "The project's latest analysis",
        "description": "Any member of the project's company (404 for another company's\nproject). The most recent analysis of the default branch's\ndependencies, vulnerabilities and licenses, whatever its status, or\n`data: null` (200) when the project has never been analysed. A\n`running` analysis whose worker did not start, or that ran longer than\n15 minutes, is marked `failed` (`error_code: TRANSIENT`) when read.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "The latest analysis, or null.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectAnalysisEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/{id}/analysis' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "startProjectAnalysis",
        "summary": "Analyse the project's default branch now",
        "description": "Company admin. Starts an analysis in the background and answers at\nonce (202) with it (`status: running`); read it with\n`GET /projects/{id}/analysis`. 429 while one is running, or within 5 minutes\nafter the last one completed or failed (a failure with `error_code:\nTRANSIENT` may be retried at once); 409 when another request started\none at the same moment. Audited as `analysis_triggered`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "202": {
            "description": "The analysis, started.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectAnalysisEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "An analysis is already running for this project."
          },
          "429": {
            "description": "An analysis is running (`analysis already running`), or the last one\ncompleted or failed less than 5 minutes ago (`the last analysis\ncompleted less than 5 minutes ago; run it again in N minutes`, with\n`Retry-After`). A temporary failure has no wait.\n",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the analysis can run again (not sent while one is running).",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/{id}/analysis' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/analysis/history": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "listProjectAnalyses",
        "summary": "The project's analyses, newest first",
        "description": "Any member of the project's company (404 for another company's project).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of analyses.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ProjectAnalysis"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/{id}/analysis/history' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/analysis/{aid}": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getProjectAnalysis",
        "summary": "One of the project's analyses",
        "description": "Any member of the project's company. 404 when the project is another company's or the analysis is not the project's. A stale `running` analysis is marked `failed` when read (as `GET /projects/{id}/analysis`).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          },
          {
            "$ref": "#/components/parameters/AnalysisId"
          }
        ],
        "responses": {
          "200": {
            "description": "The analysis.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectAnalysisEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/{id}/analysis/{aid}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/analysis/{aid}/details": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getProjectAnalysisDetails",
        "summary": "What an analysis found - dependencies, vulnerabilities, licenses",
        "description": "Any member of the project's company. 404 when the project is another company's or the analysis is not the project's. One document per kind (none yet while the analysis runs).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          },
          {
            "$ref": "#/components/parameters/AnalysisId"
          },
          {
            "name": "type",
            "in": "query",
            "description": "Only this kind (default: all three).",
            "schema": {
              "type": "string",
              "enum": [
                "deps",
                "vulns",
                "licenses"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The detail documents.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ProjectAnalysisDetail"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/{id}/analysis/{aid}/details' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/analysis/{aid}/diff": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "getProjectAnalysisDiff",
        "summary": "The vulnerabilities an analysis found new or fixed",
        "description": "Any member of the project's company. 404 when the project is another\ncompany's or the analysis is not the project's. The findings of the\nvulnerability inventory the analysis opened (new, or open again) and\nfixed: the same ones its `new_findings` and `fixed_findings` count. A\nfinding is one advisory, matched by its ID or any alias, for one\npackage version of an ecosystem, so an advisory that changes its\npreferred ID is neither new nor fixed. A project's first analysis is\nits inventory's baseline: nothing in it is new. `previous` is the\nproject's completed analysis before this one (absent: none).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          },
          {
            "$ref": "#/components/parameters/AnalysisId"
          }
        ],
        "responses": {
          "200": {
            "description": "The difference.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "new",
                            "fixed",
                            "new_total",
                            "fixed_total",
                            "incomplete",
                            "unavailable"
                          ],
                          "properties": {
                            "previous": {
                              "$ref": "#/components/schemas/ObjectId",
                              "description": "The project's completed analysis before this one (absent: this is its first)."
                            },
                            "new": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/SCAVulnerability"
                              },
                              "description": "The advisories of the findings it opened",
                              "at most 500.": null
                            },
                            "fixed": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/SCAVulnerability"
                              },
                              "description": "The advisories of the findings it fixed",
                              "at most 500.": null
                            },
                            "new_total": {
                              "type": "integer",
                              "description": "Findings it opened (the analysis's new_findings)."
                            },
                            "fixed_total": {
                              "type": "integer",
                              "description": "Findings it fixed (the analysis's fixed_findings)."
                            },
                            "incomplete": {
                              "type": "boolean",
                              "description": "A list holds fewer than its total (500 are kept of each)."
                            },
                            "unavailable": {
                              "type": "boolean",
                              "description": "The lists were removed with the analysis's details after the retention period; the totals remain."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/{id}/analysis/{aid}/diff' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/sbom": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "exportProjectSBOM",
        "summary": "The project's software bill of materials",
        "description": "Anyone who can see the project's analysis. The dependencies its default\nbranch uses as of the last analysis (with PURLs, the manifests naming\nthem and the licenses that analysis found), as CycloneDX 1.7 or\nSPDX 2.3 JSON. A dependency no PURL can be built for names none (no\nCycloneDX `purl`, no SPDX package-manager reference); its `bom-ref`\nis still its own. The licenses come from the project's latest\ncompleted analysis, whose details retention never removes. Each export is audited (`sbom_exported`). When that\nanalysis could not read everything (manifest limit, a truncated tree,\nan unreadable manifest) the document says so (CycloneDX\n`metadata.properties`, SPDX `creationInfo.comment`) and the response\ncarries `X-SBOM-Incomplete: true`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "cyclonedx",
                "spdx"
              ],
              "default": "cyclonedx"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The SBOM, as an attachment.",
            "headers": {
              "X-SBOM-Incomplete": {
                "description": "`true` when the analysis behind it could not read every manifest.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/vnd.cyclonedx+json": {
                "schema": {
                  "type": "object"
                }
              },
              "application/spdx+json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The project has not been analysed yet."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/{id}/sbom' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/monitoring/report": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "since",
          "in": "query",
          "schema": {
            "type": "string",
            "format": "date-time"
          },
          "description": "Default: 90 days ago."
        },
        {
          "name": "until",
          "in": "query",
          "schema": {
            "type": "string",
            "format": "date-time"
          },
          "description": "Default: now. At most 366 days after since."
        },
        {
          "name": "project_id",
          "in": "query",
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getMonitoringReport",
        "summary": "What change management would have done with watched repositories' merge requests",
        "description": "Any member of the company. Evaluated with the current policies from what Merge Pilot recorded (no VCS call); merge requests created or merged in the period.",
        "responses": {
          "200": {
            "description": "The report.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MonitoringReport"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/monitoring/report' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Insights"
        ],
        "operationId": "tryMonitoringReport",
        "summary": "The monitoring report with a draft policy set",
        "description": "Any member (auditors included - it changes nothing).",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "policies": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/PolicyInput"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The report.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MonitoringReport"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/monitoring/report' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/monitoring/report.csv": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "since",
          "in": "query",
          "schema": {
            "type": "string",
            "format": "date-time"
          }
        },
        {
          "name": "until",
          "in": "query",
          "schema": {
            "type": "string",
            "format": "date-time"
          }
        },
        {
          "name": "project_id",
          "in": "query",
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "downloadMonitoringReport",
        "summary": "The monitoring report's merge requests as CSV",
        "responses": {
          "200": {
            "description": "One row per merge request. Columns: Project, Merge request, Title, Author, Opened, Merged, Policy, Change type, Would be, Needs change approval, Merge held under these policies (would_have_blocked, evaluated now), Merge held when it merged (held_at_merge, as recorded then), Failing controls, Imported, Link.",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/monitoring/report.csv' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/{id}/tracker-override": {
      "put": {
        "tags": [
          "Projects"
        ],
        "operationId": "updateTrackerOverride",
        "summary": "Set the project's own change approval project key, issue type and link type",
        "description": "Company admin. Empty fields keep the tracker connection's settings.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrackerOverride"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/projects/{id}/tracker-override' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/{id}/vcs-settings": {
      "put": {
        "tags": [
          "Projects"
        ],
        "operationId": "updateProjectVCSSettings",
        "summary": "Set the project's own approver roles",
        "description": "Company admin. Exactly the given repository roles (the project's VCS\nroles) may be assigned, take and decide the project's change approvals instead of\nthe connection's; the excluded logins add to the connection's. Empty\nsettings remove the override.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSSettings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/projects/{id}/vcs-settings' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/policy-templates": {
      "get": {
        "tags": [
          "Change policies"
        ],
        "operationId": "listPolicyTemplates",
        "summary": "Built-in policy templates",
        "description": "Signed in (any role).",
        "responses": {
          "200": {
            "description": "The templates (`lightweight`, `itil`, `regulated`, `dependency_bots`).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/PolicyTemplate"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/policy-templates' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/policies": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Change policies"
        ],
        "operationId": "listPolicies",
        "summary": "List a VCS connection's policies, in order",
        "description": "Signed in (any role, own company).",
        "parameters": [
          {
            "name": "vcs_connection_id",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policies in evaluation order (the default policy last).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyListEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/policies' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Change policies"
        ],
        "operationId": "createPolicy",
        "summary": "Create a policy",
        "description": "Policy manager. The body is a `Policy` (`id`, `company_id`, `version`,\n`default`, timestamps are ignored). Unset enums get defaults\n(`change_type` normal, `on_new_commits` new_change_approval, `on_fail` block,\ncontrol modes off, licenses report, assignment random).\n`meta.warnings` lists non-fatal issues (e.g. a pool with exactly the\nrequired number of members).\n\nWith four-eyes review on, the change is queued and answered **202**\nwith `{\"pending\": true, \"change\": ConfigChange}`; it applies when a\nsecond policy manager approves it (`/companies/{id}/config-changes`).\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PolicyInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created policy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyWithWarningsEnvelope"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/PendingReview"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/policies' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/policies/match": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "post": {
        "tags": [
          "Change policies"
        ],
        "operationId": "matchPolicies",
        "summary": "Which policy applies to a described change, and why the ones above it do not",
        "description": "Signed in. Goes through the connection's policies in order. Without files or changed lines the diff counts as unknown, so policies matching on files or size do not match.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "vcs_connection_id"
                ],
                "properties": {
                  "vcs_connection_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "target_branch": {
                    "type": "string"
                  },
                  "source_branch": {
                    "type": "string"
                  },
                  "repo": {
                    "type": "string"
                  },
                  "author": {
                    "type": "string"
                  },
                  "author_bot": {
                    "type": "boolean"
                  },
                  "labels": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "draft": {
                    "type": "boolean"
                  },
                  "files": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "changed_lines": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The policies in order.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "policy_id": {
                                "$ref": "#/components/schemas/ObjectId"
                              },
                              "name": {
                                "type": "string"
                              },
                              "default": {
                                "type": "boolean"
                              },
                              "active": {
                                "type": "boolean"
                              },
                              "applies": {
                                "type": "boolean"
                              },
                              "reached": {
                                "type": "boolean"
                              },
                              "change_type": {
                                "type": "string"
                              },
                              "deny": {
                                "type": "boolean"
                              },
                              "miss": {
                                "type": "object",
                                "description": "The first condition the change does not meet.",
                                "properties": {
                                  "condition": {
                                    "type": "string",
                                    "enum": [
                                      "target_branch",
                                      "source_branch",
                                      "repo",
                                      "author_not_bot",
                                      "author_bot",
                                      "author",
                                      "label_excluded",
                                      "label_missing",
                                      "draft",
                                      "ready",
                                      "diff_unknown",
                                      "too_many_files",
                                      "too_many_lines",
                                      "path_excluded",
                                      "path_outside",
                                      "path_missing"
                                    ]
                                  },
                                  "value": {
                                    "type": "string"
                                  },
                                  "patterns": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "limit": {
                                    "type": "integer"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/match' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/policies/reevaluation": {
      "get": {
        "tags": [
          "Change policies"
        ],
        "operationId": "policyReevaluation",
        "summary": "Open merge requests still to be evaluated under changed policies",
        "description": "A policy change has the connection's open merge requests evaluated again in the background (change-managed ones first, below live events); this counts those still waiting.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "vcs_connection_id",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "How many wait.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "waiting": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/reevaluation' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/projects/evidence": {
      "post": {
        "tags": [
          "Projects"
        ],
        "operationId": "projectEvidence",
        "summary": "What was recorded while projects were watched",
        "description": "Counts the merge requests decided while the given projects were watched, and those\nmerged that change management, as it decided then, would have held. Projects of\nanother company count nothing. Any member; auditors too (it changes nothing).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "project_ids"
                ],
                "properties": {
                  "project_ids": {
                    "type": "array",
                    "maxItems": 10000,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The counts.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "recorded": {
                              "type": "integer"
                            },
                            "held": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/projects/evidence' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/projects/background": {
      "get": {
        "tags": [
          "Projects"
        ],
        "operationId": "backgroundWork",
        "summary": "What the company's background work has still to do",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "The counts.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "history_imports": {
                              "type": "integer",
                              "description": "Repositories whose past merge requests are still being imported."
                            },
                            "history_imports_done_last_hour": {
                              "type": "integer"
                            },
                            "reevaluations": {
                              "type": "integer",
                              "description": "Open merge requests waiting for changed policies."
                            },
                            "events_sync": {
                              "type": "object",
                              "description": "The last update of the projects' webhooks.",
                              "properties": {
                                "started_at": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "total": {
                                  "type": "integer"
                                },
                                "done": {
                                  "type": "integer"
                                },
                                "failed": {
                                  "type": "integer"
                                },
                                "finished_at": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "error": {
                                  "type": "string",
                                  "description": "The update stopped before every project was done."
                                }
                              }
                            },
                            "head_checks_overdue": {
                              "type": "integer"
                            },
                            "watched_overdue": {
                              "type": "integer"
                            },
                            "rate_limited": {
                              "type": "integer",
                              "description": "Jobs put off until a VCS rate limit resets."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/projects/background' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/policies/warnings": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "vcs_connection_id",
          "in": "query",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "get": {
        "tags": [
          "Change policies"
        ],
        "operationId": "policyOrderWarnings",
        "summary": "Policies that are never reached, or that match on the diff",
        "description": "Signed in. `covers_all`: no conditions, so the policies below are never reached; `shadowed`: a policy above has the same conditions or fewer; `needs_diff`: matches on files or size, which it cannot when the VCS sends no diff.",
        "responses": {
          "200": {
            "description": "Warnings.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "policy_id": {
                                "$ref": "#/components/schemas/ObjectId"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "covers_all",
                                  "shadowed",
                                  "needs_diff"
                                ]
                              },
                              "others": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/warnings' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/policies/simulate": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "post": {
        "tags": [
          "Change policies"
        ],
        "operationId": "simulatePolicies",
        "summary": "Evaluate a merge request against the stored or a draft policy set",
        "description": "Signed in (any role, auditors included - it changes nothing). 502 when the VCS cannot be read.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "merge_request_id"
                ],
                "properties": {
                  "merge_request_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "policies": {
                    "type": "array",
                    "description": "Draft policy set to try instead of the stored one.",
                    "items": {
                      "$ref": "#/components/schemas/PolicyInput"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The simulated decision.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Simulation"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/simulate' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/policies/reorder": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "put": {
        "tags": [
          "Change policies"
        ],
        "operationId": "reorderPolicies",
        "summary": "Reorder a connection's policies",
        "description": "Policy manager. The default policy stays last. 202 when four-eyes review is on.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "vcs_connection_id",
                  "policy_ids"
                ],
                "properties": {
                  "vcs_connection_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "policy_ids": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ObjectId"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The policies in their new order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyListEnvelope"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/PendingReview"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/reorder' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/policies/templates/{key}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "key",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "enum": [
              "lightweight",
              "itil",
              "regulated",
              "dependency_bots"
            ]
          }
        }
      ],
      "post": {
        "tags": [
          "Change policies"
        ],
        "operationId": "applyPolicyTemplate",
        "summary": "Apply a policy template to a connection",
        "description": "Policy manager. Replaces the connection's policies with the template's\n(additive templates add theirs above the existing ones). 202 when\nfour-eyes review is on.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "vcs_connection_id"
                ],
                "properties": {
                  "vcs_connection_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The connection's policies after applying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyListEnvelope"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/PendingReview"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/templates/{key}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/policies/{policyId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "$ref": "#/components/parameters/PolicyId"
        }
      ],
      "put": {
        "tags": [
          "Change policies"
        ],
        "operationId": "updatePolicy",
        "summary": "Update a policy",
        "description": "Policy manager. Send the whole policy with the `version` you read:\na different current version answers **409** (someone else changed it).\nThe VCS connection cannot be changed. Every save is kept as a version.\n202 when four-eyes review is on.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PolicyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved policy (version incremented).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyWithWarningsEnvelope"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/PendingReview"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/{policyId}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      },
      "delete": {
        "tags": [
          "Change policies"
        ],
        "operationId": "deletePolicy",
        "summary": "Delete a policy",
        "description": "Policy manager. The default policy cannot be deleted (400). 202 when four-eyes review is on.",
        "parameters": [],
        "responses": {
          "202": {
            "$ref": "#/components/responses/PendingReview"
          },
          "204": {
            "description": "Deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/{policyId}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/policies/{policyId}/versions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "$ref": "#/components/parameters/PolicyId"
        }
      ],
      "get": {
        "tags": [
          "Change policies"
        ],
        "operationId": "listPolicyVersions",
        "summary": "A policy's saved versions",
        "description": "Signed in (any role, own company).",
        "responses": {
          "200": {
            "description": "Immutable snapshots, one per save.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/PolicyVersion"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/policies/{policyId}/versions' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/approver-pools": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Approver pools"
        ],
        "operationId": "listApproverPools",
        "summary": "List approver pools",
        "description": "Signed in (any role, own company).",
        "responses": {
          "200": {
            "description": "The company's pools.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ApproverPool"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/approver-pools' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Approver pools"
        ],
        "operationId": "createApproverPool",
        "summary": "Create an approver pool",
        "description": "Policy manager. Members must be users of the company. A pool needs\nusers or a minimum repository role. 202 when four-eyes review is on.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApproverPoolInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created pool.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApproverPoolEnvelope"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/PendingReview"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/approver-pools' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/approver-pools/{poolId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "$ref": "#/components/parameters/PoolId"
        }
      ],
      "put": {
        "tags": [
          "Approver pools"
        ],
        "operationId": "updateApproverPool",
        "summary": "Update an approver pool",
        "description": "Policy manager. Refused (400) when a policy needs more approvals from\nthe pool than it would have members. 202 when four-eyes review is on.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApproverPoolInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The saved pool.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApproverPoolEnvelope"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/PendingReview"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/companies/{id}/approver-pools/{poolId}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      },
      "delete": {
        "tags": [
          "Approver pools"
        ],
        "operationId": "deleteApproverPool",
        "summary": "Delete an approver pool",
        "description": "Policy manager. 409 while a policy uses the pool. 202 when four-eyes review is on.",
        "parameters": [],
        "responses": {
          "202": {
            "$ref": "#/components/responses/PendingReview"
          },
          "204": {
            "description": "Deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/companies/{id}/approver-pools/{poolId}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/approver-pools/{poolId}/versions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "$ref": "#/components/parameters/PoolId"
        }
      ],
      "get": {
        "tags": [
          "Approver pools"
        ],
        "operationId": "listApproverPoolVersions",
        "summary": "A pool's saved versions",
        "description": "Signed in (any role, own company). Newest first.",
        "responses": {
          "200": {
            "description": "Versions.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ApproverPoolVersion"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/approver-pools/{poolId}/versions' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/governance/topics": {
      "get": {
        "tags": [
          "Config changes"
        ],
        "operationId": "listGovernanceTopics",
        "summary": "What waits for a second administrator when control changes are reviewed",
        "description": "Signed in. Topic keys, sorted.",
        "responses": {
          "200": {
            "description": "Topic keys (policies, approver_pools, risk, sign_in, directory, identity_providers, personal_api_tokens, vulnerability_exceptions, governance_off).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/governance/topics' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/setup-status": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getSetupStatus",
        "summary": "How far the company is set up (the setup checklist)",
        "description": "Company admins.",
        "responses": {
          "200": {
            "description": "The steps in order.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "dismissed": {
                              "type": "boolean"
                            },
                            "steps": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "enum": [
                                      "app_url",
                                      "vcs_connection",
                                      "tracker_linked",
                                      "policy",
                                      "repository",
                                      "notifications"
                                    ]
                                  },
                                  "done": {
                                    "type": "boolean"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/setup-status' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/config-changes": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Config changes"
        ],
        "operationId": "listConfigChanges",
        "summary": "List control changes waiting for (or decided by) review",
        "description": "Signed in (any role, own company).",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "applied",
                "rejected",
                "failed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The changes.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ConfigChange"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/config-changes' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "listCompanies",
        "summary": "List companies",
        "description": "Signed in. Company members get a one-element list with their own\ncompany (meta `{page:1, page_size:1, total:1, total_pages:1}`); a\nplatform admin gets a paginated list of all companies.\n",
        "parameters": [
          {
            "name": "active",
            "in": "query",
            "description": "Platform admin only. `true` lists active companies only.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Platform admin only. Search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "Companies.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Company"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getCompany",
        "summary": "Get a company",
        "description": "Signed in; members only their own company (403 otherwise). Secrets are replaced by `has_*` flags.",
        "responses": {
          "200": {
            "description": "The company.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "put": {
        "tags": [
          "Companies"
        ],
        "operationId": "updateCompany",
        "summary": "Update company settings",
        "description": "Company admin. Partial update: only the fields sent change (each\ntop-level field is replaced as a whole). There is no API-token-specific\nfield restriction: a token with the `company_admin` role may change\nevery field a company admin may change in the UI.\n\nSecrets are write-only: `smtp.password`, `ldap.bind_password` and\n`notifications.routes[].webhook_url` / `.secret` may be sent; a blank\nvalue keeps the stored one (routes are matched by `id`). A `webhook`\nroute needs an http(s) URL and a secret.\n\nWith four-eyes review on (`governance.config_approval`), a change of\n`risk_config` and switching review off are held for a second\nadministrator: the rest is applied and the answer is **202**\n`{\"company\": Company, \"pending\": [ConfigChange, ...]}`.\n\nA change of `sign_in` or `ldap` checks who could still sign in: the\ncompany's active people who have a way in now and would have none\nafter it. The ways in are a Merge Pilot password, the directory, an\nenabled identity provider (an account linked to it, or an invitation\nto link one that has not expired: `POST /users/{id}/sso-invite`) and a\nlinked VCS account while the VCS sign-in is on; each only where the\nplatform allows the method. The caller among them is refused (400\n`you would no longer be able to sign in`); others are named in a 409\nwith code `sign_in_lockout`, and the change is saved when sent again\nwith `confirm_lockout: true`.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/CompanyUpdate"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "confirm_lockout": {
                        "type": "boolean",
                        "description": "Save the sign-in change although the people named in a sign_in_lockout answer could no longer sign in."
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated company.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyEnvelope"
                }
              }
            }
          },
          "202": {
            "description": "Saved, with reviewed parts queued for four-eyes review.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "company": {
                              "$ref": "#/components/schemas/Company"
                            },
                            "pending": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/ConfigChange"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/companies/{id}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/companies/{id}/risk-config/versions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "listRiskConfigVersions",
        "summary": "Saved versions of the company's risk settings",
        "description": "Company admin.",
        "responses": {
          "200": {
            "description": "Versions.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/risk-config/versions' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/sca-results/{resultId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "resultId",
          "in": "path",
          "required": true,
          "description": "`sca_scan.result_id` of a merge request.",
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getSCAResult",
        "summary": "Full dependency scan result",
        "description": "Signed in (own company). source_findings lists the dependency source findings of the scan, up to 5000 (the merge request keeps the first 100).",
        "responses": {
          "200": {
            "description": "The SCA result document.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "additionalProperties": true,
                          "properties": {
                            "source_findings": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/SourceFinding"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/sca-results/{resultId}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/image-scan-results/{resultId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "resultId",
          "in": "path",
          "required": true,
          "description": "`image_scan.result_id` of a merge request.",
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getImageScanResult",
        "summary": "Full container image scan result",
        "description": "Signed in (own company). The vulnerable packages of each new image the merge request refers to, worst first.",
        "responses": {
          "200": {
            "description": "The image scan result.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/ImageScanResult"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/image-scan-results/{resultId}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/users/directory": {
      "get": {
        "tags": [
          "People"
        ],
        "operationId": "listDirectory",
        "summary": "The company's people (for picking pool members)",
        "description": "Directory reader. E-mail addresses are only shown to policy managers and admins.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Every user of the company.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/DirectoryEntry"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/users/directory' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/connections": {
      "get": {
        "tags": [
          "Connections"
        ],
        "operationId": "listConnections",
        "summary": "List connections",
        "description": "Signed in. Platform admins must pass `company_id`. Active connections only, unless `include_inactive=true`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "vcs",
                "tracker"
              ]
            }
          },
          {
            "name": "include_inactive",
            "in": "query",
            "description": "Also list the connections whose `active` is off (the company's Connections tab, where they are turned back on).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The company's connections (no secrets).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Connection"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/connections' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Connections"
        ],
        "operationId": "createConnection",
        "summary": "Create a connection",
        "description": "Company admin. `kind` and `provider` must match (`vcs`: `gitlab`,\n`github`; `tracker`: `jira`, `mergepilot`) and `deployment_type` must be\none the provider supports (`GET /connections/metadata`). Fill the\nconfiguration block of the provider. A GitLab VCS connection needs\n`bot_username`; GitLab and Jira connections need a `webhook_secret`. A\nGitHub cloud connection uses `https://github.com`; an on-premises one\nnames the GitHub Enterprise Server. A GitHub connection is usually\ncreated without App credentials and gets its App with\n`POST /connections/{id}/github/manifest`. The first connection of a kind\nbecomes the company's default for that kind. Secrets are write-only.\nEvery problem with the request (a missing or wrong field, an address\nMerge Pilot never calls, an unknown tracker project) answers 400 with\nthe reason in `error.message`.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConnectionInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The new connection (no secrets).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Connection"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/connections' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/connections/{id}/vcs-usage": {
      "put": {
        "tags": [
          "Connections"
        ],
        "operationId": "saveConnectionUsage",
        "summary": "Save a VCS connection's tracker link, approver settings and permissions together",
        "description": "Company admin. Every part is checked first; a refused part changes nothing. An empty `tracker_connection_id` unlinks the tracker.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tracker_connection_id": {
                    "type": "string"
                  },
                  "vcs_settings": {
                    "$ref": "#/components/schemas/VCSSettings"
                  },
                  "vcs_permissions": {
                    "$ref": "#/components/schemas/VCSPermissions"
                  },
                  "cm_steps": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "boolean"
                    },
                    "description": "Default setup steps; a required step cannot be off."
                  },
                  "cm_protection": {
                    "type": "object",
                    "description": "GitLab only (400 on GitHub): the access levels of the branch protection change management adds. A protection that exists already is left as it is.",
                    "properties": {
                      "push_level": {
                        "type": "integer",
                        "enum": [
                          0,
                          30,
                          40
                        ],
                        "default": 0,
                        "description": "0 No one, 30 Developers and Maintainers, 40 Maintainers. A level above 0 is not reported by the protection check."
                      },
                      "merge_level": {
                        "type": "integer",
                        "enum": [
                          30,
                          40
                        ],
                        "default": 30
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The connection."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/connections/{id}/vcs-usage' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/connections/{id}/cm-steps": {
      "get": {
        "tags": [
          "Connections"
        ],
        "operationId": "listSetupSteps",
        "summary": "What putting a repository under change management writes, for this connection",
        "description": "GitLab: protect_branches, bot_member, approval_rule, reset_approvals_on_push, no_approver_override, no_author_approval, no_committer_approval, webhook. GitHub: ruleset_check, require_pull_request, block_force_push, block_deletion. Required steps make the merge gate.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "The steps, in order.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "key": {
                                "type": "string"
                              },
                              "required": {
                                "type": "boolean"
                              },
                              "default_on": {
                                "type": "boolean"
                              },
                              "on": {
                                "type": "boolean",
                                "description": "On by default for this connection."
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/connections/{id}/cm-steps' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/connections/metadata": {
      "get": {
        "tags": [
          "Connections"
        ],
        "operationId": "getConnectionMetadata",
        "summary": "Supported providers, deployment types, VCS vocabulary and roles",
        "description": "For each VCS: its words (`terms`), its roles, the optional features\nMerge Pilot offers on it (`capabilities`), the options its CI variables have (`variable_features`) and\nthe roles people may give themselves by joining a project\n(`self_join_levels`).\n",
        "responses": {
          "200": {
            "description": "Provider metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                              "provider": {
                                "type": "string",
                                "enum": [
                                  "gitlab",
                                  "github",
                                  "jira",
                                  "mergepilot"
                                ]
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "vcs",
                                  "tracker"
                                ]
                              },
                              "deployment_types": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "implemented": {
                                "type": "boolean"
                              },
                              "terms": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "roles": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "level": {
                                      "type": "integer"
                                    },
                                    "name": {
                                      "type": "string"
                                    }
                                  }
                                }
                              },
                              "group_roles": {
                                "type": "array",
                                "description": "The roles in a group (GitHub: organization Member 20 and Owner 50; GitLab: the same as roles).",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "level": {
                                      "type": "integer"
                                    },
                                    "name": {
                                      "type": "string"
                                    }
                                  }
                                }
                              },
                              "capabilities": {
                                "type": "object",
                                "description": "project_directory, access_resolver,\nmember_manager, group_manager (joining groups),\ngroup_variable_manager (group CI variables),\nvariable_manager, branch_manager (listing\nbranches), branch_protector,\npipeline_resolver, tree_lister, review_reader,\nproject_token_manager (GitLab project access\ntokens and deploy tokens).\n",
                                "additionalProperties": {
                                  "type": "boolean"
                                }
                              },
                              "variable_features": {
                                "type": "object",
                                "properties": {
                                  "protected": {
                                    "type": "boolean",
                                    "description": "A variable can be limited to protected branches and tags (GitLab)."
                                  },
                                  "masked": {
                                    "type": "boolean",
                                    "description": "A value is hidden in job logs (GitLab)."
                                  },
                                  "secrets": {
                                    "type": "boolean",
                                    "description": "Write-only secrets exist besides variables (GitHub)."
                                  },
                                  "environments": {
                                    "type": "boolean",
                                    "description": "A variable or secret can belong to one deployment environment (GitHub)."
                                  },
                                  "group_visibility": {
                                    "type": "boolean",
                                    "description": "A group variable is given to selected repositories (GitHub organizations)."
                                  },
                                  "hidden": {
                                    "type": "boolean",
                                    "description": "A variable can be hidden when it is created: masked, its value never shown again (GitLab 17.4+)."
                                  },
                                  "file_type": {
                                    "type": "boolean",
                                    "description": "A variable can be a file (GitLab variable_type file)."
                                  },
                                  "raw": {
                                    "type": "boolean",
                                    "description": "Variables in the value can be left unexpanded (GitLab)."
                                  },
                                  "description": {
                                    "type": "boolean",
                                    "description": "A variable has a description (GitLab)."
                                  },
                                  "environment_scope": {
                                    "type": "boolean",
                                    "description": "A variable can be limited to environments by a free-text scope such as production or review/* (GitLab; on groups, Premium and Ultimate only)."
                                  }
                                }
                              },
                              "self_join_levels": {
                                "type": "array",
                                "description": "The access levels people may join a project with: the VCS's roles up to Developer (GitLab 10, 20, 30; GitHub 20, 25, 30).",
                                "items": {
                                  "type": "integer"
                                }
                              },
                              "vcs_ops": {
                                "type": "array",
                                "description": "The operations of vcs_permissions; min_access says whether a rule's minimum role applies.",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "key": {
                                      "type": "string"
                                    },
                                    "min_access": {
                                      "type": "boolean"
                                    }
                                  }
                                }
                              },
                              "op_roles": {
                                "type": "array",
                                "description": "The Merge Pilot roles a rule can name (user, policy_manager).",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "any_access": {
                                "type": "integer",
                                "description": "The lowest role: any access to a repository (GitLab 10, GitHub 20)."
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/connections/metadata' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/connections/{id}": {
      "get": {
        "tags": [
          "Connections"
        ],
        "operationId": "getConnection",
        "summary": "Get a connection",
        "description": "Signed in (own company; 404 otherwise).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "The connection (no secrets).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Connection"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/connections/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "put": {
        "tags": [
          "Connections"
        ],
        "operationId": "updateConnection",
        "summary": "Update a connection",
        "description": "Company admin. Send only what changes: a left-out name, `active` or\nconfiguration block is kept, and inside a configuration block an empty\nURL, user name or secret keeps the stored one. A stored token, private\nkey or secret is never sent to another host: changing the URL to a\ndifferent host needs the token (or the GitHub App private key) again\n(400 otherwise). `kind`, `provider` and `deployment_type` cannot change.\nEvery problem with the request answers 400 with the reason in\n`error.message`. Entering a new webhook secret clears the connection's\n`last_refused_webhook`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "active": {
                    "type": "boolean"
                  },
                  "gitlab_config": {
                    "$ref": "#/components/schemas/GitLabConfigInput"
                  },
                  "github_config": {
                    "$ref": "#/components/schemas/GitHubConfigInput"
                  },
                  "jira_config": {
                    "$ref": "#/components/schemas/JiraConfigInput"
                  },
                  "mergepilot_config": {
                    "$ref": "#/components/schemas/MergePilotConfigInput"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated connection (no secrets).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Connection"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/connections/{id}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      },
      "delete": {
        "tags": [
          "Connections"
        ],
        "operationId": "deleteConnection",
        "summary": "Delete a connection",
        "description": "Company admin. Refused with 409 while the connection is in use: a VCS\nconnection while repositories are watched or under change management\nthrough it (take them out on the Projects page first, so Merge Pilot\nremoves what it set up on them), a tracker while VCS connections send\ntheir change approvals to it (link them to another tracker first). When\nit was the company's default of its kind, another active connection of\nthat kind becomes the default. A VCS connection's deletion also deletes\nthe tokens people's linked accounts hold for it (the links stay,\nunusable) and releases the repository access people got by joining\nthrough it and the tokens Merge Pilot created through it\n(`released_reason: connection_deleted`, see\n`/companies/{id}/vcs-access-grants` and\n`/companies/{id}/vcs-issued-tokens`); access and tokens on the VCS are\nnot changed. Audited as `delete_connection`, and\n`vcs_access_grants_released` and `vcs_issued_tokens_released` with the\nlist when there was any.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/connections/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/connections/{id}/test": {
      "post": {
        "tags": [
          "Connections"
        ],
        "operationId": "testConnection",
        "summary": "Test a connection",
        "description": "Company admin. Calls the VCS or tracker with the stored credentials. A\nfailure answers 502 with one sentence in `error.message`: what failed\n(reaching the server, the credentials, a permission) and what the\nprovider or the network answered, for example `Jira refused the\nconnection's credentials (it answered 401 Unauthorized: ...): enter a\nvalid token or key.` or `Merge Pilot could not reach GitLab at\ngitlab.example.com: the host name does not resolve.` Secrets never\nappear in it.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Message"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/connections/{id}/test' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/connections/{id}/link-tracker": {
      "put": {
        "tags": [
          "Connections"
        ],
        "operationId": "linkTracker",
        "summary": "Link a tracker to a VCS connection",
        "description": "Company admin. The VCS connection's change approvals go to this tracker\nconnection of the same company. An empty or left-out\n`tracker_connection_id` unlinks the tracker. `PUT /connections/{id}/vcs-usage`\nsaves this together with the approver settings and permissions.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tracker_connection_id": {
                    "type": "string",
                    "description": "A tracker connection's ID; empty unlinks."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The VCS connection.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Connection"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/connections/{id}/link-tracker' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/connections/{id}/vcs-settings": {
      "put": {
        "tags": [
          "Connections"
        ],
        "operationId": "updateVCSSettings",
        "summary": "Set a VCS connection's approver settings",
        "description": "Company admin. Who may be assigned and decide change approvals. Roles\nthe VCS does not have answer 400. `PUT /connections/{id}/vcs-usage`\nsaves this together with the tracker link and permissions.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSSettings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The VCS connection.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Connection"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/connections/{id}/vcs-settings' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/connections/{id}/vcs-permissions": {
      "put": {
        "tags": [
          "Connections"
        ],
        "operationId": "updateVCSPermissions",
        "summary": "Set what people may do through a VCS connection",
        "description": "Company admin. The rules for the VCS operations people other than\ncompany admins may ask Merge Pilot to do with the connection's account\n(see the VCS operations tag). The whole set is replaced: a left-out\noperation is off. 400 when a rule names a role other than `user` or\n`policy_manager` (\"invalid permissions: <operation>: role \"…\" cannot\nbe given operations (only user, policy_manager)\"), when `min_access`\nis not one of the VCS's role levels (GitLab 10, 20, 30, 40, 50; GitHub\n20, 25, 30, 40, 50; 0 only for a rule that is off), or when it is set\nfor `join_projects` or `join_groups`, which have no minimum, or when\na rule is on for something the VCS does not have through Merge Pilot\n(GitHub: `create_access_tokens`, `create_deploy_tokens`,\n`join_groups`; \"invalid permissions: join_groups: GitHub has no\norganizations to join through Merge Pilot\"). The same checks apply to `vcs_permissions` in\n`PUT /connections/{id}/vcs-usage`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSPermissions"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The VCS connection.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Connection"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/connections/{id}/vcs-permissions' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/connections/{id}/tracker-settings": {
      "put": {
        "tags": [
          "Connections"
        ],
        "operationId": "updateTrackerSettings",
        "summary": "Set a tracker connection's change approval settings",
        "description": "Company admin. Where and how change approvals are created and which\nstatuses decide them. `project_key` and `issue_type` are required. A bad\nwork item pattern, transition path or custom field template answers\n400. On the built-in tracker, `closing_statuses` and\n`rejection_statuses` are ignored (the tracker project's final states\ndecide). Change approvals that failed to be created are tried again\nright away with the new settings.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrackerSettings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The tracker connection.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Connection"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/connections/{id}/tracker-settings' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/connections/{id}/tracker-settings/check": {
      "post": {
        "tags": [
          "Connections"
        ],
        "operationId": "checkTrackerSettings",
        "summary": "Check tracker settings against the tracker",
        "description": "Company admin. Checks the settings in the body (nothing is saved)\nagainst the tracker's create screen for the change approval's project\nand issue type. `supported: false` means the tracker cannot check\nsettings. Jira: a Description field missing from the screen is a\nproblem (every change approval is refused), and so is a missing\nAssignee field (change approvals are then created unassigned and\nassigned with a separate call, which fails for people who may not be\nassigned issues). When Jira refuses a person as a new change approval's\nassignee, the next person who may approve is tried; when it refuses\nthem all, the change approval is created unassigned and assigned with\nJira's assign call, else it stays unassigned and says why.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrackerSettings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "What the tracker found.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "supported": {
                              "type": "boolean"
                            },
                            "problems": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "What is wrong (empty when nothing is)."
                            },
                            "fields": {
                              "type": "array",
                              "description": "The fields of the create screen.",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "required": {
                                    "type": "boolean"
                                  },
                                  "type": {
                                    "type": "string",
                                    "description": "The tracker's type of the field (for Jira: string, option, array of option, ...)."
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/connections/{id}/tracker-settings/check' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/connections/{id}/tracker-options": {
      "get": {
        "tags": [
          "Connections"
        ],
        "operationId": "listTrackerOptions",
        "summary": "What tracker settings can name",
        "description": "Company admin. Lists the tracker's projects, issue types (of a\n`project`), link types, priorities or statuses (of a `project`'s\nworkflows, each once; Jira's other projects may have statuses of the\nsame names), so settings are picked rather than typed. An empty list\nmeans the tracker cannot list them. Status values are status IDs; the\nothers are keys or names.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          },
          {
            "name": "kind",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "projects",
                "issue_types",
                "link_types",
                "priorities",
                "statuses"
              ]
            }
          },
          {
            "name": "project",
            "in": "query",
            "description": "The project key, for `issue_types` and `statuses`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The options.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "value": {
                                "type": "string",
                                "description": "What a setting stores."
                              },
                              "label": {
                                "type": "string"
                              },
                              "hint": {
                                "type": "string",
                                "description": "Extra context (a status category, a link type's directions)."
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/connections/{id}/tracker-options' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/connections/{id}/people-check": {
      "get": {
        "tags": [
          "Connections"
        ],
        "operationId": "checkTrackerPeople",
        "summary": "Which tracker account each person maps to",
        "description": "Company admin. For every active person of the company (at most 300),\nthe tracker account the company's matching rule leads to, so admins\nsee who cannot be assigned or recorded as a change approval's creator.\nTracker connections only (400 otherwise).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "One entry per person.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "user_id": {
                                "type": "string"
                              },
                              "username": {
                                "type": "string"
                              },
                              "display_name": {
                                "type": "string"
                              },
                              "vcs_username": {
                                "type": "string",
                                "description": "The linked VCS account (the user name when none is linked)."
                              },
                              "tracker_name": {
                                "type": "string",
                                "description": "What the matching rule looks up (empty when there is nothing to look up)."
                              },
                              "mapped": {
                                "type": "boolean",
                                "description": "The name is the tracker account set on the person."
                              },
                              "linked": {
                                "type": "boolean",
                                "description": "The person linked a GitLab or GitHub account (needed to be assigned and to vote)."
                              },
                              "found": {
                                "type": "string",
                                "description": "The tracker account found (empty when none)."
                              },
                              "error": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/connections/{id}/people-check' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/connections/{id}/github/manifest": {
      "post": {
        "tags": [
          "Connections"
        ],
        "operationId": "startGitHubAppManifest",
        "summary": "Start registering the connection's GitHub App",
        "description": "Company admin. Starts the one-click registration of the GitHub App\nMerge Pilot acts as. The answer is a form the browser posts to GitHub\n(`manifest` as the form field `manifest`, to `action_url`); GitHub then\nsends the browser back to Merge Pilot, which stores the App's\ncredentials on the connection. The registration expires if it is not\ncompleted. 400 when the connection is not a GitHub connection or the\norganization name is not valid; 409 when the instance's Application URL\nis not set to an address GitHub can reach, or the connection already\nhas an App.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "organization": {
                    "type": "string",
                    "description": "The GitHub organization to register the App under; empty registers it under the signed-in GitHub user's account."
                  },
                  "name": {
                    "type": "string",
                    "description": "The App's name (unique per GitHub host). Default: Merge Pilot followed by the company's slug."
                  },
                  "public": {
                    "type": "boolean",
                    "default": false,
                    "description": "Lets other accounts install the App too. A private App installs only on the account it is registered under."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The form to post to GitHub.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "action_url": {
                              "type": "string"
                            },
                            "manifest": {
                              "type": "string",
                              "description": "The App manifest (JSON text)."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/connections/{id}/github/manifest' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/connections/{id}/github/installations/sync": {
      "post": {
        "tags": [
          "Connections"
        ],
        "operationId": "syncGitHubInstallations",
        "summary": "Read the GitHub App's installations again",
        "description": "Company admin. Reads from GitHub the accounts the connection's App is\ninstalled on (and the App's current name, owner, events and\npermissions, and each installation's accepted permissions and settings\npage) and stores them on the connection. GitHub also triggers this when\nan admin signed in to Merge Pilot installs the App, and with every\n`installation` event (including `new_permissions_accepted`). 400 when the connection is not a\nGitHub connection; 409 when its App has not been created yet; 502 when\nGitHub could not be reached or refused the App.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "The installations.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/GitHubInstallation"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/connections/{id}/github/installations/sync' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/connections/{id}/github/app": {
      "delete": {
        "tags": [
          "Connections"
        ],
        "operationId": "removeGitHubApp",
        "summary": "Forget the connection's GitHub App",
        "description": "Company admin. Removes the App's credentials and installations from the\nconnection (the App itself stays on GitHub; delete it there). The\nconnection then gets a new App with the manifest flow or by entering\nan App's credentials.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "204": {
            "description": "Removed."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/connections/{id}/github/app' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsGetProject",
        "summary": "Read a repository from the VCS",
        "description": "Signed in. Needs no rule. A repository not yet registered in Merge\nPilot may be read too (to set it up). Company admins may read any\nrepository the connection sees; others need some access to it on the\nVCS (any role, through their linked account).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The repository.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSProject"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/my-access": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsMyAccess",
        "summary": "What the caller may do on a repository, per operation",
        "description": "Signed in. Needs no rule; the repository need not be registered\n(setting it up is one of the operations). For every operation of\n`vcs_permissions`: whether the caller may run it here and, when not,\nwhy (`reason`, in the words the operation's 403 uses) and `code`:\n`off` (the rule is off), `role` (it does not name the caller's Merge\nPilot role), `level` (below the rule's minimum role on the repository),\n`link` (no linked VCS account), `read_only` (auditors), `unregistered`\n(the repository is not in Merge Pilot), `unverified` (the caller's\nrole could not be read). A rule that is off or does not name the\ncaller's role is reported as such (`off`, `role`) before `link` or\n`unverified`: linking an account would not change it. Company admins\nmay run everything. `view` says the caller may read what the\noperation's tab lists: true when it is allowed, and for auditors\n(`read_only`) when its rule is on; auditors read whatever their role\non the VCS, and change nothing. The project page shows only what is\nallowed or viewable. `create_access_tokens`, `create_deploy_tokens`\nand `join_groups` are left out on a VCS without them (GitHub).\n`manage_group_vars` is judged by the repository's group, as its\nwrites are: the caller's role on any of the company's repositories\nin the group counts (its `reason` then names the group).\n`connection_active` is false while the connection is turned off: every\nchange through it but taking access back is refused (409).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's access.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "admin": {
                              "type": "boolean"
                            },
                            "registered": {
                              "type": "boolean"
                            },
                            "linked": {
                              "type": "boolean",
                              "description": "The caller linked a VCS account on the connection (always true for admins)."
                            },
                            "connection_active": {
                              "type": "boolean",
                              "description": "False: the connection is turned off; every change through it is refused (409) but leaving a repository or group, cancelling an invitation and revoking a token."
                            },
                            "access_level": {
                              "type": "integer",
                              "description": "The caller's role on the repository (0: no access). Absent for admins, auditors, callers without a linked account and when it could not be read (`unverified`)."
                            },
                            "access_role": {
                              "type": "string",
                              "description": "Its name in the VCS's words, e.g. Developer."
                            },
                            "own_tokens": {
                              "type": "integer",
                              "description": "GitLab, a registered repository: how many project access and deploy tokens the caller asked for there and has not revoked. They may list and revoke them although the rules no longer let them create any (the project page then keeps the Tokens tab)."
                            },
                            "operations": {
                              "type": "object",
                              "description": "By operation (the keys of VCSPermissions).",
                              "additionalProperties": {
                                "type": "object",
                                "properties": {
                                  "allowed": {
                                    "type": "boolean"
                                  },
                                  "reason": {
                                    "type": "string"
                                  },
                                  "code": {
                                    "type": "string",
                                    "enum": [
                                      "off",
                                      "role",
                                      "level",
                                      "link",
                                      "read_only",
                                      "unregistered",
                                      "unverified"
                                    ]
                                  },
                                  "view": {
                                    "type": "boolean",
                                    "description": "May read what the operation lists: allowed, or an auditor with the rule on. Absent when false."
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/my-access' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/membership": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsProjectMembership",
        "summary": "The caller's membership of a repository",
        "description": "Signed in; needs no rule (people keep the right to read and leave\nwhat they hold; auditors read too). The repository must be registered in Merge\nPilot for the company. Reads the membership of the caller's linked VCS\naccount (400 with `code: link_required` when none is linked): on GitHub also a pending invitation;\n`granted_by_merge_pilot` says whether Merge Pilot recorded the access\nwhen the caller joined (GitLab and GitHub);\n`can_leave` says whether leaving here is possible. A recorded access\nthe VCS no longer shows is dropped (audited as\n`vcs_access_grant_dropped`, with the reason): on GitHub when the\ncaller has no access and no invitation to accept (taken back or\ndeclined on GitHub, or the invitation expired; some access left, a\nteam or the organization, keeps it: GitHub cannot tell which access\nit is); on GitLab when there is no direct membership any more.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The membership.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSMembership"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/membership' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/join": {
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsJoinProject",
        "summary": "Add the caller to a repository",
        "description": "Company admins, or people the connection's `join_projects` rule lets (on, naming their Merge Pilot role); no minimum role. The repository must be registered in Merge\nPilot for the company. Adds the caller's linked VCS account with the\nasked role, at most Developer; where the VCS invites instead, the\nanswer says so (`invited`). On GitHub the caller becomes a\ncollaborator with Read, Triage or Write: an organization member at\nonce, anyone else by an invitation to accept on GitHub. Merge Pilot\nrecords the access it gave (only that can be left here), so someone\nwho has access or a pending invitation already is refused (409). An\norganization that does not allow outside collaborators refuses the\ninvitation (403, with GitHub's message). On a repository of a\npersonal GitHub account every collaborator gets write access: only\nWrite (30) can be chosen, a lower role is refused (400). On GitLab\nthe join is recorded too (for release when the person leaves the\ncompany), and a direct member already is refused (409); when it\ncannot be recorded the join stands and the answer has a `warning`\n(on GitHub it is a 500 instead: unrecorded access could not be left).\nAudited (`vcs_join_project`, with `invited`). A connection turned off\nanswers 409.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSSelfJoin"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Joined, or invited.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "invited": {
                              "type": "boolean",
                              "description": "True when the VCS sent an invitation the caller must accept there (GitHub)."
                            },
                            "warning": {
                              "type": "string",
                              "description": "GitLab: the access was given but Merge Pilot could not record it (\"Merge Pilot could not record this access: company admins will not see it among released access if you leave the company\")."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Already a member of this project (GitHub: has access already, or an invitation is pending); or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/join' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/leave": {
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsLeaveProject",
        "summary": "Remove the caller from a repository",
        "description": "Signed in; needs no rule: someone keeps the right to give access up\nafter the joining rule is turned off or stops naming their role\n(audited with `allowed_as: member`). Auditors change nothing (403).\nWorks while the connection is turned off. The repository must be registered in Merge\nPilot for the company. 400 when the caller's linked account is not a\nmember. GitLab: 400 when it is one only through a parent group (leave\nthat instead). GitHub: only access Merge Pilot gave by joining can be\nleft: with access, the collaborator is removed (an old, expired\ninvitation on the repository does not stand in for it); without access\nyet, the pending invitation is cancelled. Other access (a team, the\norganization, a repository admin), or access released when its person\nleft the company, answers 409. No access and no invitation answers 400\nand drops Merge Pilot's record (`vcs_access_grant_dropped`). On GitLab\na direct membership is removed whether Merge Pilot recorded it or not.\nAudited (`vcs_leave_project`, with `invitation_cancelled` on GitHub).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "Left, or the invitation cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "invitation_cancelled": {
                              "type": "boolean",
                              "description": "True when a pending invitation was cancelled (GitHub)."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "GitHub: Merge Pilot did not give this access; it is managed on GitHub."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/leave' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/groups": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsListGroups",
        "summary": "Groups that hold the company's repositories",
        "description": "Company admins, or people the connection's `join_groups` rule lets (on, naming their Merge Pilot role); no minimum role. Lists one page of the groups the connection's\naccount sees and keeps only those holding a repository registered in\nMerge Pilot for the company (so a page can have fewer than `per_page`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "name": "search",
            "in": "query",
            "description": "Passed to the VCS's group search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The groups.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VCSGroup"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/groups' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/groups/{gid}/membership": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsGroupMembership",
        "summary": "The caller's membership of a group",
        "description": "Signed in; needs no rule (as for leaving). The group must hold a repository registered in\nMerge Pilot for the company (404 otherwise). Reads the membership of\nthe caller's linked VCS account, with `granted_by_merge_pilot`\n(Merge Pilot recorded it when the caller joined); a recorded\nmembership GitLab no longer shows is dropped\n(`vcs_access_grant_dropped`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSGroupId"
          }
        ],
        "responses": {
          "200": {
            "description": "`{\"is_member\": false, \"granted_by_merge_pilot\": false}`, or the membership (`is_member`, `access_level`, `username`, `granted_by_merge_pilot`).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSMembership"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/groups/{gid}/membership' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/groups/{gid}/join": {
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsJoinGroup",
        "summary": "Add the caller to a group",
        "description": "Company admins, or people the connection's `join_groups` rule lets (on, naming their Merge Pilot role); no minimum role. The group must hold a repository registered in\nMerge Pilot for the company. Adds the caller's linked VCS account with\nthe asked role, at most Developer. A group role reaches every project\nof the group and its subgroups, so every one of them must be\nregistered to the company: otherwise 403 \"Merge Pilot does not add\nyou to this group, because a role in it reaches every project of the\ngroup and its subgroups, and the group holds projects that are not\nthe company's in Merge Pilot\" (also when the group's projects cannot\nbe read or are too many to check), audited as a failed\n`vcs_join_group` with `refused`. A group shared with (invited into)\nother groups gives its direct members access there too, so for anyone\nbut a company admin joining it is refused (403 \"acme is shared with\nother groups (partner): joining it would also give access there; ask\na company admin\", also when the sharing cannot be read), audited the\nsame way. The join is recorded (for release when the person leaves\nthe company); when it cannot be, the answer has a `warning`. Audited\n(`vcs_join_group`, with `group_path`). A connection turned off\nanswers 409.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSGroupId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSSelfJoin"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Joined.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "warning": {
                              "type": "string",
                              "description": "The access was given but Merge Pilot could not record it."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Already a member of this group; or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/groups/{gid}/join' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/vcs-ops/groups/{gid}/leave": {
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsLeaveGroup",
        "summary": "Remove the caller from a group",
        "description": "Signed in; needs no rule (audited with `allowed_as: member` when the\njoining rule would refuse the caller). Auditors change nothing (403).\nWorks while the connection is turned off. The group must hold a repository registered in\nMerge Pilot for the company. Removes the caller's linked VCS account\nand forgets Merge Pilot's record of it.\nAudited (`vcs_leave_group`, with `group_path`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSGroupId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Message"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/groups/{gid}/leave' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/variables": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsListProjectVariables",
        "summary": "A repository's CI/CD variables and secrets",
        "description": "Company admins, or people the connection's `view_variables` or `manage_project_vars` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least that rule's `min_access` on the repository (403 with the first refusal's reason otherwise): changing the variables serves listing them. Auditors read it with any of these rules on, whatever their role on the VCS (values stay left out). The repository must be registered in Merge\nPilot for the company. Secrets (`secret: true`) come without their\nvalue. GitHub: the repository's Actions variables and secrets, then\neach environment's (`environment_scope` names it); environments the\nApp may not read yet are left out (see the environments route).\nWhat cannot be read is left out instead of failing the list, and\n`warnings` names it: an environment GitHub does not answer for (for\nexample deleted meanwhile), or all of them when the App may not list\nor read them (naming the permission). GitLab answers no warnings.\nValues: a masked or hidden variable's value is never returned, to\nanyone (company admins included), nor a secret's. Other values are\nreturned only to callers who may change the repository's variables\n(company admins, or the `manage_project_vars` rule lets them); for\neveryone else `value` is left out and `value_hidden` is true.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The variables.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "variables",
                            "warnings"
                          ],
                          "properties": {
                            "variables": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/VCSVariable"
                              }
                            },
                            "warnings": {
                              "type": "array",
                              "description": "What could not be read and is left out, in words (for example \"Could not read the variables and secrets of environment staging: GitHub answered 404: Not Found\").",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/variables' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsCreateProjectVariable",
        "summary": "Create a CI/CD variable or secret on a repository",
        "description": "Company admins, or people the connection's `manage_project_vars` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least its `min_access` on the repository (403 with the reason otherwise). The repository must be\nregistered in Merge Pilot for the company. Audited\n(`vcs_create_project_var`, with the environment, without the value).\nGitHub: `secret: true` creates an Actions secret, encrypted with the\nscope's public key; `environment_scope` names an environment, which\nmust exist (404 \"environment X does not exist in the repository;\ncreate it in the repository settings on GitHub\"); a name already\ntaken, in any case, answers 409; `protected` and `masked` answer 501.\nA permission the GitHub App lacks answers 403 naming it. GitHub's\nname rules and size limit are checked first (400, nothing sent to\nGitHub): letters, digits and underscores only, no leading digit, no\n`GITHUB_` prefix (in any case), values up to 48 KB (48,000 bytes).\nAnother refusal by GitHub (422) answers 400 with GitHub's message.\nGitLab: `environment_scope` (default `*`), `variable_type` (`env_var`\nor `file`), `raw` (left out: GitLab's default, true), `description`,\n`protected`, `masked`, and `hidden` (masked, and the value is never\nshown again; GitLab 17.4+, only when creating). GitLab has no\nsecrets (`secret: true` answers 400). A value GitLab does not accept\n(for example one that cannot be masked) answers 400 with GitLab's\nmessage. Options the VCS's variables do not have answer 400 (\"GitHub\nvariables cannot be files\", \"... have no description\", \"... have no\nraw option\", \"... cannot be hidden; use a secret\"). The answer never\ncarries the value of a masked, hidden or secret variable. The audit\nrecords the options (`variable_type`, `raw`, `hidden`), never the\nvalue.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSVariableInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The variable.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSVariable"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The variable or secret exists already (or the VCS reports another conflict); or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/variables' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/variables/{key}": {
      "put": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsUpdateProjectVariable",
        "summary": "Change a repository's CI/CD variable or secret",
        "description": "The same access and checks as creating one (`manage_project_vars`).\nThe variable is named by `key`, `environment` and `secret`; it must\nexist (404 otherwise: an update never creates one). The value is\nalways sent (a hidden or secret value cannot be read back); options\nleft out are kept. The key, environment scope and hidden state do\nnot change (`hidden` in the body answers 400). GitLab: the project's\nvariables are read first and the one of that key and environment\nscope is changed (`PUT` with `filter[environment_scope]`): a scope\nit does not have answers 404 \"no variable named X with environment\nscope Y\", several of the key without `environment` answer 400; a\nhidden variable stays masked (`masked: false` answers 400). GitHub:\na variable's value is changed (`PATCH`), a secret is encrypted and\nreplaced (`PUT`) once it is found; only the value can change\n(`protected`/`masked` answer 501); the same name and size rules as\ncreating one. Audited (`vcs_update_project_var`, with the\nenvironment and the options changed, never the value). The answer\nnever carries the value of a masked, hidden or secret variable.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "secret",
            "in": "query",
            "description": "`true`: the variable is a write-only secret (GitHub). GitLab has no secrets: `true` answers 501.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "environment",
            "in": "query",
            "description": "GitHub: the environment the variable or secret belongs to (none: the repository's own). GitLab: its environment scope (none: the only variable of the key).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSVariableUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The variable as changed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSVariable"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The VCS reports a conflict changing it (its message); or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/variables/{key}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      },
      "delete": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsDeleteProjectVariable",
        "summary": "Delete a repository's CI/CD variable or secret",
        "description": "Company admins, or people the connection's `manage_project_vars` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least its `min_access` on the repository (403 with the reason otherwise). The repository must be\nregistered in Merge Pilot for the company. Audited\n(`vcs_delete_project_var`, with the environment).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "secret",
            "in": "query",
            "description": "`true`: the variable is a write-only secret (GitHub). GitLab has no secrets: `true` answers 501.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "environment",
            "in": "query",
            "description": "GitHub: the environment the variable or secret belongs to (none: the repository's own). GitLab: its environment scope, sent as filter[environment_scope] (GitLab 13.4+), so only that variable is deleted when several share the key; without it GitLab refuses an ambiguous delete (409 \"There are multiple variables with provided parameters. Please use 'filter[environment_scope]'.\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ConnectionOff"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/variables/{key}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/environments": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsListEnvironments",
        "summary": "A repository's deployment environments (GitHub)",
        "description": "Company admins, or people the `view_variables`, `manage_project_vars` or `manage_group_vars` rule lets, as listing the repository's variables checks them. Auditors read it with any of these rules on, whatever their role on the VCS. The environments\na variable or secret can be limited to. When the GitHub App may not\nuse their variables and secrets yet (the installation lacks the\n\"Environments\" permission), `unavailable_reason` says so; the names\nare still listed. When the App may not list the environments (the\n\"Actions\" permission), the list is empty and `unavailable_reason`\nnames that permission. GitLab answers 501.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The environments' names.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "environments"
                          ],
                          "properties": {
                            "environments": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "unavailable_reason": {
                              "type": "string",
                              "description": "Why environment variables and secrets cannot be used yet (a permission the GitHub App lacks)."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/environments' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/group": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsProjectGroup",
        "summary": "The group (GitHub organization) a repository belongs to",
        "description": "Company admins, or people the connection's `view_variables` or `manage_group_vars` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least that rule's `min_access` on any of the company's registered repositories in the group, as the group's variables are judged (403 with the first refusal's reason otherwise). Auditors read it with any of these rules on, whatever their role on the VCS. The repository must be registered in Merge\nPilot for the company. The group whose variables the project page\noffers: GitLab, the project's namespace when it is a group; GitHub,\nthe owning organization when the connection's App is installed on it\n(`id` is its login). 404 for a personal namespace or account.\n`can_manage` says whether the caller may change the group's\nvariables, judged as those writes are (company admins; otherwise\nthe `manage_group_vars` rule, and the caller's role on any of the\ncompany's registered repositories in the group); when not,\n`manage_reason` says why.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The group.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/VCSGroup"
                            },
                            {
                              "type": "object",
                              "required": [
                                "can_manage"
                              ],
                              "properties": {
                                "can_manage": {
                                  "type": "boolean",
                                  "description": "The caller may change the group's variables."
                                },
                                "manage_reason": {
                                  "type": "string",
                                  "description": "Why not, e.g. this needs at least Maintainer in GitLab on one of the company's repositories in this group. Absent when can_manage."
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/group' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/groups/{gid}/variables": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsListGroupVariables",
        "summary": "A group's CI/CD variables and secrets",
        "description": "Company admins, or people the connection's `view_variables` or `manage_group_vars` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least that rule's `min_access` on one of the company's registered repositories in the group (no group role is asked; 403 \"this needs at least <role> in <VCS> on one of the company's repositories in this group\" otherwise): changing the variables serves listing them. Auditors read it with any of these rules on, whatever their role on the VCS (values stay left out). The group\nmust hold a repository registered in Merge Pilot for the company.\nOnly the variables the company's registered repositories can use are\nlisted, each with `can_change` and, when false, `read_only_reason`:\na variable may change here only when every repository that can use it\nis the company's. GitHub: the group is an organization the\nconnection's App is installed on, named by its login; its Actions\nvariables and secrets, with their `visibility`. `all` is listed and\nread only; `private` is listed when one of the company's repositories\nthere is private, and read only; `selected` is listed when its\nrepositories include one of the company's, and may change when they\nare all the company's (one selected-repositories list is read per\nsuch variable). GitLab: a group variable reaches every project of the\ngroup and its subgroups: listed, and changeable only when all of them\nare registered to the company (read only when the group is too large\nto check). A caller the `manage_group_vars` rule does not let gets\nevery item read only with that reason. Values are sent as for a\nrepository's variables, only for items the caller may change\n(`can_change`): never for masked or hidden variables, nor secrets;\n`value_hidden` marks a value left out.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSGroupId"
          }
        ],
        "responses": {
          "200": {
            "description": "The variables.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VCSGroupVariable"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/groups/{gid}/variables' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsCreateGroupVariable",
        "summary": "Create a CI/CD variable or secret on a group",
        "description": "Company admins, or people the connection's `manage_group_vars` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least its `min_access` on one of the company's registered repositories in the group (no group role is asked; 403 \"this needs at least <role> in <VCS> on one of the company's repositories in this group\" otherwise). The group must hold a\nrepository registered in Merge Pilot for the company. Audited\n(`vcs_create_group_var`, with `visibility` and `repository_count`,\nwithout the value). GitHub: an organization variable or secret with\nvisibility `selected`, given to exactly the company's repositories in\nthe organization registered in Merge Pilot on this connection (the\ncaller cannot choose them; repositories registered later are not\nadded). GitHub Free does not give organization values to private\nrepositories. GitHub's name rules and 48 KB value limit answer 400,\nas for repository variables. GitLab: a group variable reaches every\nproject of the group and its subgroups, so every one of them must be\nregistered to the company (as for deleting one): otherwise 403\n\"Merge Pilot does not create this variable, because every project of\nthe group and its subgroups could use it, and the group holds\nprojects that are not the company's in Merge Pilot\", audited as a\nfailed `vcs_create_group_var` with `refused`. The GitLab options\n(`environment_scope`, Premium and Ultimate only on groups;\n`variable_type`, `raw`, `description`, `hidden`) are as for a\nrepository's variables.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSGroupId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSVariableInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The variable.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSVariable"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The variable or secret exists already (or the VCS reports another conflict); or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/groups/{gid}/variables' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/vcs-ops/groups/{gid}/variables/{key}": {
      "put": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsUpdateGroupVariable",
        "summary": "Change a group's CI/CD variable or secret",
        "description": "The same access as creating one (`manage_group_vars`), and only a\nvariable whose whole reach is the company's registered repositories,\nas for deleting one: one the company's repositories cannot use, or\nof no such key, kind and environment scope, answers 404; one other\nrepositories can use too answers 403 with the reason (audited as a\n`vcs_update_group_var` failure with `refused`). The body is as for a\nrepository's variable. GitLab: GitLab's own update falls back to\nanother scope's variable of the key when the scope asked for does\nnot exist, so Merge Pilot finds the variable first and sends\n`filter[environment_scope]` (Premium and Ultimate) only when it is\nneeded to tell variables of the key apart. GitHub: an organization\nvariable's value changes (`PATCH`, its visibility and repositories\nkept); a secret is replaced with the same visibility and selected\nrepositories. Audited (`vcs_update_group_var`, never the value).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSGroupId"
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "secret",
            "in": "query",
            "description": "`true`: the variable is a write-only secret (GitHub). GitLab has no secrets: `true` answers 501.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "environment",
            "in": "query",
            "description": "GitLab: the variable's environment scope (none: the only variable of the key).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VCSVariableUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The variable as changed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSVariable"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The VCS reports a conflict changing it (its message); or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/vcs-ops/groups/{gid}/variables/{key}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      },
      "delete": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsDeleteGroupVariable",
        "summary": "Delete a group's CI/CD variable or secret",
        "description": "Company admins, or people the connection's `manage_group_vars` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least its `min_access` on one of the company's registered repositories in the group (no group role is asked; 403 \"this needs at least <role> in <VCS> on one of the company's repositories in this group\" otherwise). The group must hold a\nrepository registered in Merge Pilot for the company. Only a variable\nwhose whole reach is the company's registered repositories is deleted\n(see the list): one the company's repositories cannot use answers 404,\none other repositories can use too answers 403 with the reason\n(audited as a `vcs_delete_group_var` failure with `refused`). Audited\n(`vcs_delete_group_var`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSGroupId"
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "secret",
            "in": "query",
            "description": "`true`: the variable is a write-only secret (GitHub). GitLab has no secrets: `true` answers 501.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "environment",
            "in": "query",
            "description": "GitHub: the environment the variable or secret belongs to (none: the repository's own). GitLab: its environment scope; sent as filter[environment_scope] only when it is not `*` (GitLab has it for group variables from 16.9, Premium and Ultimate).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ConnectionOff"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/vcs-ops/groups/{gid}/variables/{key}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/branches": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsListBranches",
        "summary": "A repository's branches",
        "description": "Company admins, or people one of the connection's `protect_branches`, `unprotect_branches` and `force_push` rules lets (on, naming their Merge Pilot role) whose linked VCS account holds at least that rule's `min_access` on the repository (403 with the first rule's reason otherwise). The repository must be registered in Merge Pilot for the\ncompany. GitLab: every page of branches (100 a page), up to 10,000;\nbeyond that the first 10,000 are listed and `warning` says a search\nnarrows the list. GitHub: every branch; `protected` marks the\nbranches Merge Pilot protects with a ruleset of their own.\n`cm_gated` marks the branches under change management (the project\nis gated and the branch matches its target branches, the default\nbranch token resolved, and none of its excluded branches).\nAuditors read it with any of the branch rules on, whatever their role on the VCS.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          },
          {
            "name": "search",
            "in": "query",
            "description": "GitLab: passed to its branch search (`^term` and `term$` anchor it). GitHub: the names that contain it (any case).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The branches.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "branches"
                          ],
                          "properties": {
                            "branches": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/VCSBranch"
                              }
                            },
                            "warning": {
                              "type": "string",
                              "description": "The VCS has more branches than were listed; a search narrows the list. Absent when the list is whole."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/branches' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/protected-branches": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsListProtectedBranches",
        "summary": "A repository's protected branches",
        "description": "Company admins, or people one of the connection's `protect_branches`, `unprotect_branches` and `force_push` rules lets (on, naming their Merge Pilot role) whose linked VCS account holds at least that rule's `min_access` on the repository (403 with the first rule's reason otherwise). The repository must be registered in Merge Pilot for the\ncompany. Auditors read it with any of the three rules on, whatever their role on the VCS.\nGitHub: every `Merge Pilot protected: <branch>` ruleset; one\nwhose content is no longer what Merge Pilot wrote (its branches,\nenforcement, bypass list or rules were changed on GitHub) has\n`changed_on_vcs` and `changed_reason`.\n`cm_gated` marks the branches under change management (the project\nis gated and the branch matches its target branches, the default\nbranch token resolved, and none of its excluded branches), and the\nGitLab wildcard patterns that can cover one (see protecting a\nbranch).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The protected branches.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VCSProtectedBranch"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/protected-branches' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsProtectBranch",
        "summary": "Protect a branch",
        "description": "Company admins, or people the connection's `protect_branches` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least its `min_access` on the repository (403 with the reason otherwise). The repository must be registered in Merge Pilot for the company.\nAudited (`vcs_protect_branch`, with `cm_gated`).\nNames (all three branch writes, both VCSs): a leading `refs/heads/`\nis dropped, so `refs/heads/main` is `main`; other `refs/` names, a\nname with spaces around it and an empty name answer 400 before the\nVCS is asked.\nOn a gated project, a non-admin's GitLab wildcard pattern (a name\nwith `*`, `?` or `[`) that can cover a branch under change management\n(it matches the default branch or a target branch, or a target is a\npattern itself) is refused for protecting, unprotecting and force\npushes alike: GitLab applies the most permissive of the protections\nmatching a branch. 403 \"this pattern can cover a branch under change\nmanagement; only a company admin can change protection with it\",\naudited as a failure with `refused` and `cm_gated`.\n\nGitHub: creates the repository ruleset `Merge Pilot protected: <branch>`\n(rules deletion, non_fast_forward and pull_request). Refused with 409\nwhen Merge Pilot protects the branch already or the repository has\nGitHub's maximum of 75 rulesets; with 403 when GitHub refuses rulesets\n(private repositories need GitHub Team, Pro or Enterprise; the App\nneeds the Administration permission). The name is trimmed and a\nleading `refs/heads/` dropped; other `refs/` names, and names with a\npattern character (`* ? [ ] { }`), answer 400: one branch by its\nexact name.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The branch to protect. GitLab also takes a wildcard pattern; GitHub one branch by its exact name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Message"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The VCS reports a conflict (e.g. the branch is protected already, or GitHub's ruleset limit is reached); or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/protected-branches' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/protected-branches/{name}": {
      "delete": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsUnprotectBranch",
        "summary": "Remove a branch's protection",
        "description": "Company admins, or people the connection's `unprotect_branches` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least its `min_access` on the repository (403 with the reason otherwise). The repository must be registered in Merge Pilot for the\ncompany. Audited (`vcs_unprotect_branch`). GitHub: deletes only the\nbranch's `Merge Pilot protected: <branch>` ruleset; 404 when Merge\nPilot does not protect the branch; 409 when the ruleset was changed\non GitHub (it is changed or removed there, never deleted silently).\nOn a branch under change management (`cm_gated`) only company admins\nmay: anyone else gets 403 \"this branch is under change management;\nonly a company admin can change its protection\", audited as a\nfailure with `refused` and `cm_gated`; a wildcard pattern that can\ncover one is refused the same way (see protecting a branch). The\nname is read as when protecting (`refs/heads/main` is `main`).\nGitLab: change management's approval rule for a gated branch is\nlinked to the branch's protection, so an admin's unprotect of a gated\nbranch answers 200 with a `warning` that the rule is no longer linked\nto the branch and that running change management setup again\nrestores it (also in the audit entry); otherwise 204.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The protected branch's name.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Unprotected, with a warning (GitLab, a branch under change management).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "warning": {
                              "type": "string",
                              "description": "What unprotecting the branch cost."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "204": {
            "description": "Unprotected."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "GitHub: the branch's ruleset was changed on GitHub; change or remove it there; or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/protected-branches/{name}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/protected-branches/{name}/force-push": {
      "patch": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsSetForcePush",
        "summary": "Allow or forbid force pushes to a protected branch",
        "description": "Company admins, or people the connection's `force_push` rule lets (on, naming their Merge Pilot role) whose linked VCS account holds at least its `min_access` on the repository (403 with the reason otherwise).\nThe repository must be registered in Merge Pilot for the company.\nAudited (`vcs_toggle_force_push`, with the warning).\n\nGitHub: removes (or puts back) the non_fast_forward rule of the\nbranch's `Merge Pilot protected: <branch>` ruleset; 404 when Merge\nPilot does not protect the branch. Rulesets add up, so when force\npushes are allowed but another ruleset (such as the merge gate's)\nstill blocks them, `warning` names it. The change is done once GitHub\nsaved the ruleset: when looking up the other rulesets fails, the\nanswer has no warning. The branch's classic branch protection is\nnamed too when it blocks force pushes (`allow_force_pushes` off);\nwhen it cannot be read (best effort), it is not named. 409 when the\nruleset was changed on GitHub.\nOn a branch under change management (`cm_gated`) only company admins\nmay, whichever way (allowing or forbidding force pushes): anyone else\ngets 403 \"this branch is under change management; only a company\nadmin can change its protection\", audited as a failure with\n`refused` and `cm_gated`; a wildcard pattern that can cover one is\nrefused the same way (see protecting a branch). The name is read as\nwhen protecting (`refs/heads/main` is `main`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The protected branch's name.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "allow"
                ],
                "properties": {
                  "allow": {
                    "type": "boolean",
                    "description": "true: force pushes are allowed; false: forbidden. Left out (or a body that is not JSON) answers 400 \"allow (true or false) is required\"."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Changed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "message"
                          ],
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "warning": {
                              "type": "string",
                              "description": "What else on the VCS still blocks force pushes to the branch (GitHub: the other rulesets, by name). Absent when nothing does."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "GitHub: the branch's ruleset was changed on GitHub; change or remove it there; or the connection is turned off (`this connection is turned off: ask a company admin`)."
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PATCH 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/protected-branches/{name}/force-push' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/tokens": {
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsListTokens",
        "summary": "Tokens Merge Pilot created on a repository (GitLab)",
        "description": "The project access tokens and deploy tokens Merge Pilot created on\nthe registered repository, newest first (at most 500), never their\nvalues. Company admins, people the connection's\n`create_access_tokens` or `create_deploy_tokens` rule lets (with its\n`min_access` on the repository; auditors when the rule is on,\nwhatever their role on the VCS, revoking none), and whoever asked\nfor one of the listed tokens; 403 otherwise. Whether\neach still works is read from GitLab (`status`); `warnings` say when\na list could not be read (the status then comes from the records).\n501 on GitHub.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "tokens": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/VCSIssuedToken"
                              }
                            },
                            "warnings": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/tokens' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/access-tokens": {
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsCreateAccessToken",
        "summary": "Create a GitLab project access token",
        "description": "Company admins, or people the connection's `create_access_tokens`\nrule lets (on, naming their Merge Pilot role) whose linked VCS account\nholds at least its `min_access` on the registered repository (403\nwith the reason otherwise). Merge Pilot's GitLab account creates it,\nso it needs Maintainer or Owner on the project; on GitLab.com project\naccess tokens need Premium or Ultimate.\n400 before GitLab is asked: `name` missing; `description` over 255\ncharacters; `scopes` empty, repeated or outside `read_api`,\n`read_repository`, `write_repository`, `read_registry`,\n`write_registry` (`api` and `self_rotate` are never given: a token\nwith the whole API, or one renewing itself past its expiry);\n`access_level` not 10, 20 or 30, or (non-admins) above the caller's\nown role on the repository; `expires_at` missing, not a date, not\nafter today (UTC), or more than 365 days away. The answer holds the\ntoken's value once; it is never stored, logged or audited. Audited\nas `vcs_create_access_token`. On GitHub the rule cannot be turned\non, so others get 403; a company admin gets 501.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "scopes",
                  "access_level",
                  "expires_at"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string",
                    "description": "Up to 255 characters; GitLab keeps it from 17.7."
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "read_api",
                        "read_repository",
                        "write_repository",
                        "read_registry",
                        "write_registry"
                      ]
                    }
                  },
                  "access_level": {
                    "type": "integer",
                    "enum": [
                      10,
                      20,
                      30
                    ]
                  },
                  "expires_at": {
                    "type": "string",
                    "format": "date",
                    "description": "YYYY-MM-DD: after today, at most 365 days away."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created; the value is in this answer only.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSCreatedToken"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ConnectionOff"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/access-tokens' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/deploy-tokens": {
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsCreateDeployToken",
        "summary": "Create a GitLab deploy token",
        "description": "Company admins, or people the connection's `create_deploy_tokens`\nrule lets, as for access tokens. Merge Pilot's GitLab account needs\nMaintainer or Owner on the project. 400 before GitLab is asked:\n`name` missing; `scopes` empty, repeated or outside\n`read_repository`, `read_registry`, `write_registry`,\n`read_package_registry`, `write_package_registry`,\n`read_virtual_registry`, `write_virtual_registry`; a scope above\nthe caller's own role on the repository (a deploy token has no role\nof its own; company admins count as Developer): `read_repository`,\n`read_registry` and `read_package_registry` need Reporter,\n`write_registry` and `write_package_registry` Developer, the two\nvirtual registry scopes any role (\"scope \"write_registry\" needs at\nleast Developer on this repository (you have Reporter)\");\n`expires_at` missing, not after today or more than 365 days away\n(Merge Pilot's own limit: GitLab lets deploy tokens never expire).\nThe answer holds the value once. Audited as\n`vcs_create_deploy_token`. On GitHub the rule cannot be turned on,\nso others get 403; a company admin gets 501.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "scopes",
                  "expires_at"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "username": {
                    "type": "string",
                    "description": "Empty: GitLab names it gitlab+deploy-token-{n}."
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "read_repository",
                        "read_registry",
                        "write_registry",
                        "read_package_registry",
                        "write_package_registry",
                        "read_virtual_registry",
                        "write_virtual_registry"
                      ]
                    }
                  },
                  "expires_at": {
                    "type": "string",
                    "format": "date",
                    "description": "YYYY-MM-DD: after today, at most 365 days away."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created; the value is in this answer only.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VCSCreatedToken"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/ConnectionOff"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/deploy-tokens' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/vcs-ops/projects/{pid}/tokens/{token_id}": {
      "delete": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "vcsRevokeToken",
        "summary": "Revoke a token Merge Pilot created",
        "description": "The person who asked for the token (even once the rule is off),\ncompany admins, or people the rule for its kind lets (with its\n`min_access` on the repository); 403 otherwise. GitLab revokes it\nand the record is marked revoked; a token GitLab no longer has is\nmarked revoked with a `warning`. 409 \"this token is revoked already\"\n(also to the second of two revokes at once: one is audited). Works\nwhile the connection is turned off.\nAudited as `vcs_revoke_token` (`allowed_as: requester` for the\nrequester). On GitHub no token is ever recorded, so the answer is\n404.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSConnectionIdQuery"
          },
          {
            "$ref": "#/components/parameters/VCSProjectId"
          },
          {
            "name": "token_id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "warning": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/vcs-ops/projects/{pid}/tokens/{token_id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/mptracker/projects": {
      "get": {
        "tags": [
          "Tracker"
        ],
        "operationId": "listTrackerProjects",
        "summary": "List tracker projects",
        "parameters": [
          {
            "name": "include_archived",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Projects.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/TrackerProject"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/mptracker/projects' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Tracker"
        ],
        "operationId": "createTrackerProject",
        "summary": "Create a tracker project",
        "description": "Company admin. `mode` `vcs` projects hold change approvals; `manual` projects hold hand-made issues.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "prefix",
                  "mode"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "prefix": {
                    "type": "string",
                    "description": "Issue key prefix (e.g. `CMG`): 2-10 upper-case letters and digits, starting with a letter."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "vcs",
                      "manual"
                    ]
                  },
                  "description": {
                    "type": "string"
                  },
                  "issue_types": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "states": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/TrackerState"
                    }
                  },
                  "closing_states": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "rejection_states": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "allowed_transitions": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "default_issue_type": {
                    "type": "string"
                  },
                  "custom_fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "description": "VCS mode: the fields instead of the default reviewer fields and review check boxes."
                  },
                  "no_custom_fields": {
                    "type": "boolean",
                    "description": "VCS mode: start without any custom fields (they can be added later)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/mptracker/projects' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/mptracker/projects/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ResourceId"
        }
      ],
      "get": {
        "tags": [
          "Tracker"
        ],
        "operationId": "getTrackerProject",
        "summary": "Get a tracker project",
        "responses": {
          "200": {
            "description": "The project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/mptracker/projects/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "put": {
        "tags": [
          "Tracker"
        ],
        "operationId": "updateTrackerProject",
        "summary": "Update a tracker project",
        "description": "Company admin. States in use are protected; `rename_from` maps old state names to new ones.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "issue_types": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "states": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/TrackerState"
                    }
                  },
                  "closing_states": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "rejection_states": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "allowed_transitions": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "default_issue_type": {
                    "type": "string"
                  },
                  "custom_fields": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/TrackerCustomField"
                    }
                  },
                  "rename_from": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerProjectEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/mptracker/projects/{id}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      },
      "delete": {
        "tags": [
          "Tracker"
        ],
        "operationId": "archiveTrackerProject",
        "summary": "Archive a tracker project",
        "description": "Company admin.",
        "parameters": [],
        "responses": {
          "204": {
            "description": "Archived."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/mptracker/projects/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/mptracker/projects/{id}/issues": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ResourceId"
        }
      ],
      "get": {
        "tags": [
          "Tracker"
        ],
        "operationId": "listTrackerIssues",
        "summary": "List a project's issues",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "issue_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Case-insensitive search in the summary.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assigned_to_me",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "assignee",
            "in": "query",
            "description": "Assignee username (ignored when `assigned_to_me=true`).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of issues (meta includes `total_pages`).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/TrackerIssue"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/mptracker/projects/{id}/issues' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Tracker"
        ],
        "operationId": "createTrackerIssue",
        "summary": "Create an issue (manual-mode projects)",
        "description": "Signed in (not auditors). Change approvals of `vcs` projects are created by Merge Pilot itself.\nEvery custom field required at creation must be given; a field set only during\ntransitions cannot be (400). An archived project answers 409. The issue starts in\nthe state with the lowest `order`.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "issue_type",
                  "summary"
                ],
                "properties": {
                  "issue_type": {
                    "type": "string"
                  },
                  "summary": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "assignee_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "custom_fields": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerIssueEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/mptracker/projects/{id}/issues' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/mptracker/projects/{id}/board": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ResourceId"
        }
      ],
      "get": {
        "tags": [
          "Tracker"
        ],
        "operationId": "getTrackerBoard",
        "summary": "Issues grouped by state (kanban board)",
        "parameters": [
          {
            "name": "limit_per_state",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Only this state's column (for its next page, with `offset`).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Issues of each column to skip (how many the board shows already).",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "issue_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assigned_to_me",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "assignee",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Columns.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "total": {
                              "type": "integer"
                            },
                            "columns": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "state": {
                                    "$ref": "#/components/schemas/TrackerState"
                                  },
                                  "issues": {
                                    "type": "array",
                                    "items": {
                                      "$ref": "#/components/schemas/TrackerIssue"
                                    }
                                  },
                                  "total": {
                                    "type": "integer"
                                  },
                                  "has_more": {
                                    "type": "boolean"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/mptracker/projects/{id}/board' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/mptracker/issues/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ResourceId"
        }
      ],
      "get": {
        "tags": [
          "Tracker"
        ],
        "operationId": "getTrackerIssue",
        "summary": "Get an issue",
        "responses": {
          "200": {
            "description": "The issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerIssueEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/mptracker/issues/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "put": {
        "tags": [
          "Tracker"
        ],
        "operationId": "updateTrackerIssue",
        "summary": "Update an issue's summary, description, type or custom fields",
        "description": "Optimistic concurrency - send the `version` you read; a stale version answers 409,\nand so does an issue of an archived project. Only the custom fields sent are checked:\na field required at creation cannot be cleared (400). On a change approval, a review\nattestation (a field required before an approving or rejecting state) is changed only\nby who may decide it, never the MR author (403).\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "version"
                ],
                "properties": {
                  "summary": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "issue_type": {
                    "type": "string"
                  },
                  "custom_fields": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "version": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerIssueEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X PUT 'https://merge-pilot.example.com/api/v1/mptracker/issues/{id}' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/mptracker/issues/by-key/{key}": {
      "get": {
        "tags": [
          "Tracker"
        ],
        "operationId": "getTrackerIssueByKey",
        "summary": "Get an issue by key (e.g. a change approval key)",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerIssueEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/mptracker/issues/by-key/{key}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/mptracker/issues/{id}/transition": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ResourceId"
        }
      ],
      "post": {
        "tags": [
          "Tracker"
        ],
        "operationId": "transitionTrackerIssue",
        "summary": "Move an issue to another state",
        "description": "Only allowed transitions; required custom fields of the target state\nmust be set (400). On a change approval, moving to an approving or rejecting state,\nor changing a review attestation with the move, is a decision and follows the\napproval rules (403 when the caller may not decide). Moving an approved change\napproval out of its approving state withdraws the approval when an approver of the\nchange or an admin does it; anyone else's move is undone by Merge Pilot. Stale\n`version`, or an archived project, answers 409.\n",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "state",
                  "version"
                ],
                "properties": {
                  "state": {
                    "type": "string"
                  },
                  "version": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "custom_fields": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerIssueEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/mptracker/issues/{id}/transition' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/mptracker/issues/{id}/assign": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ResourceId"
        }
      ],
      "post": {
        "tags": [
          "Tracker"
        ],
        "operationId": "assignTrackerIssue",
        "summary": "Assign an issue",
        "description": "Manual-mode projects (VCS-mode projects answer 422). Stale `version`, or an archived project, answers 409.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "user_id",
                  "version"
                ],
                "properties": {
                  "user_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "version": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackerIssueEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "description": "The project is in VCS mode: its issues' assignee cannot be changed\n(`error.code = assignee_immutable`, `error.field_key = assignee`).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/mptracker/issues/{id}/assign' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/mptracker/issues/{id}/comments": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ResourceId"
        }
      ],
      "get": {
        "tags": [
          "Tracker"
        ],
        "operationId": "listTrackerComments",
        "summary": "List an issue's comments",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of comments.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/TrackerComment"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/mptracker/issues/{id}/comments' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Tracker"
        ],
        "operationId": "addTrackerComment",
        "summary": "Comment on an issue",
        "description": "An issue of an archived project answers 409.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "body"
                ],
                "properties": {
                  "body": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The comment.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TrackerComment"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/mptracker/issues/{id}/comments' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/mptracker/users": {
      "get": {
        "tags": [
          "Tracker"
        ],
        "operationId": "searchTrackerUsers",
        "summary": "Search the company's active users by prefix (for assignee pickers)",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching users.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/mptracker/users' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/audit-logs": {
      "get": {
        "tags": [
          "Audit"
        ],
        "operationId": "listAuditLogs",
        "summary": "Search the audit log",
        "description": "Audit reader. Platform admins see all companies unless `company_id` is given; `scope=platform` lists the entries of no company.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "scope",
            "in": "query",
            "description": "`platform`: only the entries that belong to no company (platform settings, the license, platform admin accounts and their sign-ins, failed sign-ins of unknown user names). Platform admins only (403 otherwise); `company_id` is then ignored.",
            "schema": {
              "type": "string",
              "enum": [
                "platform"
              ]
            }
          },
          {
            "name": "action",
            "in": "query",
            "description": "Exact match (e.g. `change_approval_vote`, `policy_updated`).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resource",
            "in": "query",
            "description": "Exact match (e.g. `merge_request`, `policy`, `api_token`).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Exact match (`success`, `failure`, ...).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "username",
            "in": "query",
            "description": "Exact match. Service tokens appear as `token:<name>`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "RFC 3339.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "RFC 3339.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search in username and action.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "name": "sort",
            "in": "query",
            "description": "`created_at`, `username`, `action` or `status`; prefix `-` for descending. Default `-created_at`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of audit entries.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/AuditLog"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/audit-logs' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/webhook-logs": {
      "get": {
        "tags": [
          "Audit"
        ],
        "operationId": "listWebhookLogs",
        "summary": "Inbound webhook log (VCS and tracker events received)",
        "description": "Audit reader. Newest first.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search in source and event type.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of webhook log entries.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/WebhookLog"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/webhook-logs' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/compliance/report": {
      "get": {
        "tags": [
          "Audit"
        ],
        "operationId": "getComplianceReport",
        "summary": "Export the compliance report (CSV or PDF)",
        "description": "Audit reader. Platform admins must pass `company_id`. Dates are days in\nthe company's time zone (end day included); default the last 30 days.\nLarge reports are truncated; see the `X-Report-*` headers. The export\nis recorded in the audit log.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "pdf"
              ],
              "default": "csv"
            }
          },
          {
            "name": "date_basis",
            "in": "query",
            "description": "opened_at: when the merge request was opened on the VCS.",
            "schema": {
              "type": "string",
              "enum": [
                "merged_at",
                "opened_at"
              ],
              "default": "merged_at"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "YYYY-MM-DD or RFC 3339.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "YYYY-MM-DD or RFC 3339.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The report file (attachment).",
            "headers": {
              "X-Report-Truncated": {
                "description": "The sections cut at their limit, comma-separated: merge_requests, audit_entries, direct_changes (empty: none).",
                "schema": {
                  "type": "string"
                }
              },
              "X-Report-Total-MRs": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Report-Returned-MRs": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Report-Total-Audit-Entries": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Report-Returned-Audit-Entries": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Report-Total-Direct-Changes": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Report-Returned-Direct-Changes": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/compliance/report' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/dashboard": {
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getDashboard",
        "summary": "Dashboard overview",
        "description": "Signed in. Platform admins without `company_id` get all companies.\n`recent_events` (the latest audit log entries) is `null` for a role\nthat may not read the audit log (policy manager, user).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/AnyObject"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/dashboard' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/dashboard/stats": {
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getDashboardStats",
        "summary": "Dashboard counters",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/AnyObject"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/dashboard/stats' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/dashboard/cycle-time": {
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getDashboardCycleTime",
        "summary": "Cycle time summary",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/Window"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/AnyObject"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/dashboard/cycle-time' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/dashboard/change-calendar": {
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getChangeCalendar",
        "summary": "Changes per day of a month",
        "description": "Platform admins must pass `company_id`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "month",
            "in": "query",
            "description": "`YYYY-MM`; default the current month.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/AnyObject"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/dashboard/change-calendar' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/dora": {
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getDORAMetrics",
        "summary": "DORA metrics",
        "description": "Signed in. Platform admins must pass `company_id`. Deployments are\nmerges into the given branches, or (none given) into each\nrepository's default branch. Results are cached briefly per\ncompany/window/branches.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/Window"
          },
          {
            "name": "branches",
            "in": "query",
            "description": "Comma-separated deployment branches; default each repository's default branch.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The metrics.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DORAMetrics"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/dora' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/analytics/cycle-time": {
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getCycleTimeAnalytics",
        "summary": "Cycle time analytics",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          },
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "7d",
                "30d",
                "90d"
              ],
              "default": "30d"
            }
          },
          {
            "name": "include_median",
            "in": "query",
            "description": "Company admins only (403 otherwise).",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/AnyObject"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/analytics/cycle-time' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/analytics/bottlenecks": {
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getBottlenecks",
        "summary": "Where merge requests wait",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          },
          {
            "name": "window",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "7d",
                "30d",
                "90d"
              ],
              "default": "30d"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/AnyObject"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/analytics/bottlenecks' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/my-work": {
      "get": {
        "tags": [
          "Insights"
        ],
        "operationId": "getMyWork",
        "summary": "The caller's open work (authored MRs, change approvals to decide)",
        "description": "Signed in. The merge requests the caller authored, matched by their\nlinked VCS accounts (with none linked, by their Merge Pilot username),\nin three sections: open ones that need the author's attention (at most\n50; watched ones are left out), open ones (at most 50) and those merged\nor closed in the last 14 days (at most 20). Items carry a subset of the merge request's fields. Cached\nfor a few seconds per person.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "The sections and their counts.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "needs_attention": {
                              "type": "object",
                              "properties": {
                                "items": {
                                  "type": "array",
                                  "items": {
                                    "allOf": [
                                      {
                                        "$ref": "#/components/schemas/MergeRequest"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "reasons": {
                                            "type": "array",
                                            "description": "Why the author has to act: found secrets, a blocking control that failed (sca, licenses, package health, dependency sources, CI configuration, signatures, CI, code review, work items, risk, freeze) or a rejected change approval.",
                                            "items": {
                                              "$ref": "#/components/schemas/AttentionReason"
                                            }
                                          },
                                          "primary_reason": {
                                            "$ref": "#/components/schemas/AttentionReason"
                                          }
                                        }
                                      }
                                    ]
                                  }
                                },
                                "has_more": {
                                  "type": "boolean"
                                }
                              }
                            },
                            "in_progress": {
                              "type": "object",
                              "properties": {
                                "items": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/MergeRequest"
                                  }
                                },
                                "has_more": {
                                  "type": "boolean"
                                }
                              }
                            },
                            "recently_completed": {
                              "type": "object",
                              "properties": {
                                "items": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/components/schemas/MergeRequest"
                                  }
                                },
                                "has_more": {
                                  "type": "boolean"
                                }
                              }
                            },
                            "summary": {
                              "type": "object",
                              "description": "The number of items returned in each section.",
                              "properties": {
                                "attention_count": {
                                  "type": "integer"
                                },
                                "in_progress_count": {
                                  "type": "integer"
                                },
                                "completed_count": {
                                  "type": "integer"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/my-work' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/delegations": {
      "get": {
        "tags": [
          "Delegations"
        ],
        "operationId": "listDelegations",
        "summary": "Current and future delegations",
        "description": "Signed in. Company admins see all of the company's; others see the ones\nthey give or receive. `meta.mode` is the company's delegation mode\n(`off`, `self`, `admin`, `both`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Delegations, by start.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Delegation"
                          }
                        },
                        "meta": {
                          "type": "object",
                          "properties": {
                            "mode": {
                              "type": "string",
                              "enum": [
                                "off",
                                "self",
                                "admin",
                                "both"
                              ]
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/delegations' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      },
      "post": {
        "tags": [
          "Delegations"
        ],
        "operationId": "createDelegation",
        "summary": "Hand an approver's votes to someone else for a while",
        "description": "A person (not a service token). Without `user_id` the caller delegates\ntheir own votes (mode `self` or `both`); with `user_id` a company admin\nsets one up for someone (mode `admin` or `both`). Both people must be\nactive users of the company; at most 180 days; overlapping\ndelegations answer 409.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "delegate_id",
                  "from",
                  "until"
                ],
                "properties": {
                  "user_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "delegate_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "from": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "until": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The delegation.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Delegation"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/delegations' \\\n  -H 'Authorization: Bearer <token>' \\\n  -H 'Content-Type: application/json' \\\n  -d @body.json"
          }
        ]
      }
    },
    "/delegations/people": {
      "get": {
        "tags": [
          "Delegations"
        ],
        "operationId": "listDelegationPeople",
        "summary": "People who can be chosen as delegate",
        "description": "The company's active users by name, at most 200; `meta.has_more` says more exist, and `q` finds them.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          },
          {
            "name": "q",
            "in": "query",
            "description": "Case-insensitive search in username and display name.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "People.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "$ref": "#/components/schemas/ObjectId"
                              },
                              "username": {
                                "type": "string"
                              },
                              "display_name": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "meta": {
                          "type": "object",
                          "properties": {
                            "has_more": {
                              "type": "boolean"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/delegations/people' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/delegations/{id}": {
      "delete": {
        "tags": [
          "Delegations"
        ],
        "operationId": "deleteDelegation",
        "summary": "End a delegation",
        "description": "The approver, whoever set it up, or a company admin.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          },
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "$ref": "#/components/parameters/CompanyIdHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "Ended."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/delegations/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vcs-access-grants": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "listVCSAccessGrants",
        "summary": "Repository and group access people got through Merge Pilot",
        "description": "Company admin. `released=true`: the access Merge Pilot no longer\ntracks because its person was deactivated, moved to another company,\nmade platform admin or unlinked their VCS account, the repository\nwas removed from Merge Pilot, the connection was deleted or the\ncompany deactivated (`released_reason`). Releasing never changes\naccess on the VCS, so it may still exist there; newest release first.\nA release that failed is retried hourly (audited with `sweep: true`).\nOtherwise the access Merge Pilot tracks (people leave it on the\nproject page or in the groups list). At most 500.\n",
        "parameters": [
          {
            "name": "released",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The grants.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VCSAccessGrant"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/vcs-access-grants' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vcs-access-grants/{grant_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "grant_id",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "delete": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "dismissVCSAccessGrant",
        "summary": "Dismiss a released access record",
        "description": "Company admin. Deletes the record of released access (the access on\nthe VCS is not changed: remove it there first if it should go).\nA tracked grant answers 409. Audited as `vcs_access_grant_dismissed`.\n",
        "parameters": [],
        "responses": {
          "204": {
            "description": "Dismissed."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/companies/{id}/vcs-access-grants/{grant_id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vcs-issued-tokens": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "listReleasedVCSTokens",
        "summary": "Released tokens that may still work",
        "description": "Company admin. The project access tokens and deploy tokens Merge\nPilot created for people who were deactivated, moved to another\ncompany or made platform admin, or through a deleted connection.\nOffboarding never revokes them on GitLab. Newest release first, at\nmost 500. Tokens revoked or expired before the release are not\nreleased.\n",
        "responses": {
          "200": {
            "description": "The released tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VCSIssuedToken"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/vcs-issued-tokens' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vcs-issued-tokens/{token_id}/revoke": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "token_id",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "post": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "revokeReleasedVCSToken",
        "summary": "Revoke a released token",
        "description": "Company admin. Merge Pilot's account revokes the released token on\nGitLab; the record stays, marked revoked, until dismissed. 409 when\nit is revoked already, still tracked, or its connection was deleted\n(revoke it on the VCS, then dismiss it). A token GitLab no longer\nhas is marked revoked with a `warning`. 501 when the connection's\nVCS has no such tokens. Audited as `vcs_revoke_token`.\n",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "message"
                          ],
                          "properties": {
                            "message": {
                              "type": "string"
                            },
                            "warning": {
                              "type": "string",
                              "description": "GitLab no longer had the token (revoked or deleted there): it is marked revoked."
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/VCSRateLimited"
          },
          "501": {
            "$ref": "#/components/responses/NotImplemented"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/vcs-issued-tokens/{token_id}/revoke' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/vcs-issued-tokens/{token_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "token_id",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "delete": {
        "tags": [
          "VCS operations"
        ],
        "operationId": "dismissReleasedVCSToken",
        "summary": "Dismiss a released token's record",
        "description": "Company admin. Deletes the record of a released token (the token on\nGitLab is not changed). A tracked token answers 409. Audited as\n`vcs_issued_token_dismissed`.\n",
        "parameters": [],
        "responses": {
          "204": {
            "description": "Dismissed."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X DELETE 'https://merge-pilot.example.com/api/v1/companies/{id}/vcs-issued-tokens/{token_id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/notification-deliveries": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Notification deliveries"
        ],
        "operationId": "listNotificationDeliveries",
        "summary": "The delivery log",
        "description": "Company admin. A page of the company's deliveries, newest first: to\nits routes (every channel) and personal emails (`channel` `person`).\nEach is tried up to 5 times with back-off (a mail server's 5xx refusal\nfails at once) and kept 7 days, whatever its status. See the\n`WebhookEvent` schema for what a webhook route is sent. 400 for a\nfilter value not listed.\n",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "delivered",
                "failed",
                "skipped"
              ]
            }
          },
          {
            "name": "route",
            "in": "query",
            "description": "Only this notification route's deliveries (its `id`).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event",
            "in": "query",
            "description": "Only this event type, or `test` for route tests.",
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/WebhookEventType"
                },
                {
                  "type": "string",
                  "const": "test"
                }
              ]
            }
          },
          {
            "name": "channel",
            "in": "query",
            "description": "Only this channel; `person` for personal emails.",
            "schema": {
              "type": "string",
              "enum": [
                "slack",
                "teams",
                "email",
                "webhook",
                "person"
              ]
            }
          },
          {
            "name": "user",
            "in": "query",
            "description": "Only this person's personal emails (a user ID).",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of deliveries.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/NotificationDelivery"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/notification-deliveries' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/notification-deliveries/failures": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Notification deliveries"
        ],
        "operationId": "countFailedNotificationDeliveries",
        "summary": "Deliveries that failed for good",
        "description": "Company admin. How many deliveries failed for good in the delivery history (the last 7 days), per route, the most first (`route_id` empty for personal emails). The Notifications tab's banner and each route's failed count.",
        "responses": {
          "200": {
            "description": "The failures.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "total": {
                              "type": "integer"
                            },
                            "since": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "by_route": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "route_id": {
                                    "type": "string"
                                  },
                                  "count": {
                                    "type": "integer"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/notification-deliveries/failures' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/notification-deliveries/{did}/redeliver": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        },
        {
          "name": "did",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "post": {
        "tags": [
          "Notification deliveries"
        ],
        "operationId": "redeliverNotification",
        "summary": "Send a delivery again now",
        "description": "Company admin. The same message is sent again (a webhook delivery keeps its body and delivery ID, with a new timestamp and signature). A delivered, failed or skipped delivery goes to every recipient of an email route again, clearing `delivered_to` and `refused_to`. A pending delivery waiting for its next attempt is only moved to now: the recipients it already reached or that refused it are kept. A delivery being sent right now is refused with 409 (`the delivery is being sent right now: send it again when this attempt has finished`). Earlier attempts are kept. Audited as `notification_redelivered`.",
        "parameters": [],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Message"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/companies/{id}/notification-deliveries/{did}/redeliver' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/companies/{id}/notification-routes/inactive-recipients": {
      "parameters": [
        {
          "$ref": "#/components/parameters/CompanyIdPath"
        }
      ],
      "get": {
        "tags": [
          "Notification deliveries"
        ],
        "operationId": "listInactiveRouteRecipients",
        "summary": "Route addresses of deactivated people",
        "description": "Company admin. Of the addresses given, those that belong to deactivated people of the company (compared without case), who still get the email routes that name them. At most 200 addresses (400).",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "description": "An address; repeat for several.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": "The addresses of deactivated people.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "inactive": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/companies/{id}/notification-routes/inactive-recipients' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/jobs": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "listJobs",
        "summary": "List background jobs",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "status",
            "in": "query",
            "description": "`processing` also lists the jobs just picked up (`claimed`).",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "claimed",
                "processing",
                "completed",
                "failed",
                "retry"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of jobs.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Job"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/jobs' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/jobs/stats": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "getJobStats",
        "summary": "Job counts by status",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/AnyObject"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/jobs/stats' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/jobs/{id}": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "getJob",
        "summary": "Get a job",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "description": "The job.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Job"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/jobs/{id}' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/jobs/{id}/retry": {
      "post": {
        "tags": [
          "Jobs"
        ],
        "operationId": "retryJob",
        "summary": "Queue a job again",
        "description": "Company admin or platform admin (403 otherwise), own company. Recorded in the audit log as `job_retried`. 409 when a job for the same work is already queued or running.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ResourceId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Message"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/jobs/{id}/retry' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/health-checks": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "listHealthChecks",
        "summary": "Recorded health checks of the services Merge Pilot calls",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          },
          {
            "name": "service",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_healthy",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of checks.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/health-checks' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/health-checks/summary": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "getHealthCheckSummary",
        "summary": "Latest state per connection",
        "description": "One entry per connection checked in the last 24 hours (a connection\ndeleted since is left out): `service` (the provider: `gitlab`,\n`github`, `jira`), `connection_id`, `connection_name` (its current\nname), `company_slug`, `current_status` (the latest check passed),\n`last_check`, `latency_ms`, `error_msg` (when it failed) and\n`uptime_percent_24h`. Each recorded check (`GET /health-checks`)\ncarries its `connection_id`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "The connections' latest state.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "service": {
                                "type": "string",
                                "enum": [
                                  "gitlab",
                                  "github",
                                  "jira"
                                ]
                              },
                              "connection_id": {
                                "$ref": "#/components/schemas/ObjectId"
                              },
                              "connection_name": {
                                "type": "string"
                              },
                              "company_slug": {
                                "type": "string"
                              },
                              "current_status": {
                                "type": "boolean",
                                "description": "The latest check passed."
                              },
                              "last_check": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "latency_ms": {
                                "type": "integer"
                              },
                              "error_msg": {
                                "type": "string",
                                "description": "Why the latest check failed."
                              },
                              "uptime_percent_24h": {
                                "type": "number"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/health-checks/summary' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/health-checks/notifications": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "listNotificationFailuresByCompany",
        "summary": "Companies with failed notification deliveries",
        "description": "The companies whose notification deliveries failed for good in the last 7 days, the most first (a company user sees their own company only).",
        "parameters": [
          {
            "$ref": "#/components/parameters/CompanyIdQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "The companies.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "company_id": {
                                "$ref": "#/components/schemas/ObjectId"
                              },
                              "company_slug": {
                                "type": "string"
                              },
                              "company_name": {
                                "type": "string"
                              },
                              "failed": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/health-checks/notifications' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/scanner/rules": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "listScannerRules",
        "summary": "Secret scanner rules",
        "responses": {
          "200": {
            "$ref": "#/components/responses/AnyObject"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/scanner/rules' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/healthz": {
      "servers": [
        {
          "url": "https://{host}",
          "variables": {
            "host": {
              "default": "merge-pilot.example.com",
              "description": "Your Merge Pilot host name"
            }
          }
        }
      ],
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "liveness",
        "summary": "Liveness probe (outside /api/v1)",
        "security": [],
        "responses": {
          "200": {
            "description": "The process is up."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/healthz' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/readyz": {
      "servers": [
        {
          "url": "https://{host}",
          "variables": {
            "host": {
              "default": "merge-pilot.example.com",
              "description": "Your Merge Pilot host name"
            }
          }
        }
      ],
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "readiness",
        "summary": "Readiness probe (outside /api/v1)",
        "security": [],
        "responses": {
          "200": {
            "description": "Ready (database reachable)."
          },
          "503": {
            "description": "Not ready."
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/readyz' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/version": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "getVersion",
        "summary": "The running release",
        "description": "The Merge Pilot release this instance runs, for any signed-in account or\nAPI token. The probes above do not tell it.\n",
        "responses": {
          "200": {
            "description": "The release.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "required": [
                            "version"
                          ],
                          "properties": {
                            "version": {
                              "type": "string",
                              "example": "2.0.6"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/version' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/instances": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "listInstances",
        "summary": "The running instances",
        "description": "Platform admins. The server instances that make up this installation,\nthe longest running first: each reports in every few seconds; one not\nseen for three of them is left out, and one that stops gently leaves at\nonce. The API and webhook request limits are shared out among them.\n",
        "responses": {
          "200": {
            "description": "The running instances.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "hostname",
                              "version",
                              "started_at",
                              "seen_at"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The host name and a random part (instances on one host are separate).",
                                "example": "merge-pilot-backend-7d9f-1a2b3c4d"
                              },
                              "hostname": {
                                "type": "string"
                              },
                              "version": {
                                "type": "string",
                                "example": "2.0.7"
                              },
                              "started_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "seen_at": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Its last heartbeat."
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/instances' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/settings/urls": {
      "get": {
        "tags": [
          "Platform"
        ],
        "operationId": "getPlatformUrls",
        "summary": "The addresses Merge Pilot is reached at",
        "description": "Signed in. The public addresses (no secrets) and the sign-in methods\nthe platform allows, for building webhook URLs and showing which\nsign-in methods a company may turn on.\n",
        "responses": {
          "200": {
            "description": "The addresses.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "app_url": {
                              "type": "string",
                              "description": "Address the VCS and the tracker send webhooks to."
                            },
                            "public_url": {
                              "type": "string"
                            },
                            "frontend_url": {
                              "type": "string"
                            },
                            "sign_in_methods": {
                              "$ref": "#/components/schemas/SignInMethods"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/settings/urls' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/license/status": {
      "get": {
        "tags": [
          "Platform"
        ],
        "operationId": "getLicenseStatus",
        "summary": "License state (any signed-in account)",
        "description": "Signed in. Used by the product to warn about a missing or expired license.",
        "responses": {
          "200": {
            "description": "The license state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LicenseStateEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/license/status' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/debug/mr/{id}/flow": {
      "parameters": [
        {
          "$ref": "#/components/parameters/MergeRequestId"
        }
      ],
      "get": {
        "tags": [
          "Diagnostics"
        ],
        "operationId": "getMergeRequestFlow",
        "summary": "A merge request's event flow",
        "description": "Platform admin (the Debug page under Insights). The merge request's\nwebhooks, jobs and audit entries in time order, for tracing what\nhappened to it. An unknown ID answers 404 `merge request not found`.\n",
        "security": [],
        "responses": {
          "200": {
            "description": "The events.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/FlowEvent"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/debug/mr/{id}/flow' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/debug/webhooks/{id}/replay": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The webhook log entry's ID (`id` from `GET /webhook-logs`).",
          "schema": {
            "$ref": "#/components/schemas/ObjectId"
          }
        }
      ],
      "post": {
        "tags": [
          "Diagnostics"
        ],
        "operationId": "replayWebhook",
        "summary": "Replay a received webhook",
        "description": "Platform admin (the Debug page under Insights). Processes a received\nmerge request webhook again, as a new job. An unknown webhook answers\n404 (with `dry_run=true` too). At most 10 replays per webhook and one\nper minute: over those the answer is 429 (`this webhook was replayed 10\ntimes, the most allowed`, or `... replay it again in N seconds` with\n`Retry-After`). A webhook whose VCS connection cannot be found answers\n400 with the reason.\n\nWith `dry_run=true` nothing is queued: the answer says what a replay\nwould do.\n",
        "security": [],
        "parameters": [
          {
            "name": "dry_run",
            "in": "query",
            "description": "`true`: preview only.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The replay was queued (`{\"message\": \"replay started\", \"job_id\": \"...\"}`),\nor, with `dry_run=true`, the preview.\n",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "message": {
                                  "type": "string"
                                },
                                "job_id": {
                                  "type": "string"
                                }
                              }
                            },
                            {
                              "type": "object",
                              "properties": {
                                "will_create_job": {
                                  "type": "boolean",
                                  "description": "False when the VCS connection cannot be found: a replay would fail."
                                },
                                "job_type": {
                                  "type": "string"
                                },
                                "side_effects": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "attempt_no": {
                                  "type": "integer",
                                  "description": "The number this replay would have."
                                }
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Replayed the most times allowed, or less than a minute ago.",
            "headers": {
              "Retry-After": {
                "description": "Seconds until the webhook can be replayed again (only for the once-a-minute limit).",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X POST 'https://merge-pilot.example.com/api/v1/debug/webhooks/{id}/replay' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    },
    "/api-calls": {
      "get": {
        "tags": [
          "Diagnostics"
        ],
        "operationId": "listAPICalls",
        "summary": "Calls Merge Pilot made to the VCS and the tracker",
        "description": "Platform admin (the API monitor under Insights). Merge Pilot's calls\nto GitLab, GitHub and Jira, newest first, with status and latency.\n",
        "security": [],
        "parameters": [
          {
            "name": "service",
            "in": "query",
            "description": "Only calls to this service.",
            "schema": {
              "type": "string",
              "enum": [
                "gitlab",
                "github",
                "jira"
              ]
            }
          },
          {
            "name": "company_id",
            "in": "query",
            "description": "Only calls made for this company.",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "is_success",
            "in": "query",
            "description": "`true`: successful calls only; `false`: failed calls only.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Called at or after (RFC 3339). An unparsable value is ignored.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Called at or before (RFC 3339). An unparsable value is ignored.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Case-insensitive search in the endpoint path and method.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of calls.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/APICall"
                          }
                        },
                        "meta": {
                          "$ref": "#/components/schemas/PaginationMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "curl",
            "source": "curl -X GET 'https://merge-pilot.example.com/api/v1/api-calls' \\\n  -H 'Authorization: Bearer <token>'"
          }
        ]
      }
    }
  },
  "webhooks": {
    "mergePilotEvent": {
      "post": {
        "summary": "Outbound event sent to a company's webhook notification route",
        "description": "Sent to every active notification route with `channel_type: webhook`\nwhose `events` include the event type (or `all`) and whose\n`path_patterns` (if any) match the project path. Delivery is retried\nwith exponential back-off up to 5 attempts; any 2xx answer counts as\ndelivered. A request times out after 10 seconds.\n\nRedirects are not followed: a 3xx answer is a failed attempt.\n\n**Signature.** `X-MergePilot-Signature` is `sha256=` followed by the\nlowercase hex HMAC-SHA256 of the `X-MergePilot-Timestamp` value, a dot\nand the **raw request body** (exactly the bytes received), keyed with\nthe route's secret. Refuse a timestamp more than a few minutes old. A\nredelivery sends the same body and `X-MergePilot-Delivery` with a new\ntimestamp and signature; use the delivery ID to drop duplicates.\n",
        "security": [],
        "parameters": [
          {
            "name": "X-MergePilot-Timestamp",
            "in": "header",
            "required": true,
            "description": "When the request was sent (Unix seconds).",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]+$"
            }
          },
          {
            "name": "X-MergePilot-Signature",
            "in": "header",
            "required": true,
            "description": "`sha256=<hex HMAC-SHA256(route secret, timestamp + \".\" + raw body)>`",
            "schema": {
              "type": "string",
              "pattern": "^sha256=[0-9a-f]{64}$"
            }
          },
          {
            "name": "X-MergePilot-Delivery",
            "in": "header",
            "required": true,
            "description": "Delivery ID (stable across retries and redeliveries).",
            "schema": {
              "$ref": "#/components/schemas/ObjectId"
            }
          },
          {
            "name": "X-MergePilot-Event",
            "in": "header",
            "required": true,
            "description": "The event type (same as `event` in the body).",
            "schema": {
              "$ref": "#/components/schemas/WebhookEventType"
            }
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Merge-Pilot-Webhook"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered."
          },
          "default": {
            "description": "Any other answer (or no answer) is retried."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Merge Pilot API token (mpt_...)",
        "description": "API token: `Authorization: Bearer mpt_...`. Create service tokens in\nCompany -> API tokens (company admins) and personal tokens in My profile.\nTokens expire after 1 to 365 days. When a token is sent, browser cookies\non the same request are ignored and CSRF does not apply. A request with\nan invalid, expired or revoked token (or a token of an inactive company)\nis answered `401 \"invalid, expired or revoked API token\"`.\n"
      }
    },
    "parameters": {
      "UnsubscribeToken": {
        "name": "t",
        "in": "query",
        "required": true,
        "description": "The signed token of a personal email's unsubscribe link.",
        "schema": {
          "type": "string"
        }
      },
      "CompanyIdQuery": {
        "name": "company_id",
        "in": "query",
        "required": false,
        "description": "Platform admins only - the company to act on (ignored for company members, who always act on their own company).",
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "CompanyIdHeader": {
        "name": "X-Company-ID",
        "in": "header",
        "required": false,
        "description": "Platform admins only - alternative to `company_id` on per-company endpoints.",
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "CompanyIdPath": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Company ID. Members may only use their own company (404 otherwise).",
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "ResourceId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "MergeRequestId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Merge Pilot's merge request ID (not the VCS number; see `/merge-requests/lookup`).",
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "AnalysisId": {
        "name": "aid",
        "in": "path",
        "required": true,
        "description": "Project analysis ID.",
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "PolicyId": {
        "name": "policyId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "PoolId": {
        "name": "poolId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "Page": {
        "name": "page",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      },
      "PageSize": {
        "name": "page_size",
        "in": "query",
        "description": "Values above 100 are capped at 100.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      "Window": {
        "name": "window",
        "in": "query",
        "description": "Unknown values fall back to `30d`.",
        "schema": {
          "type": "string",
          "enum": [
            "7d",
            "30d",
            "90d"
          ],
          "default": "30d"
        }
      },
      "VCSConnectionIdQuery": {
        "name": "connection_id",
        "in": "query",
        "required": false,
        "description": "The company's VCS connection to act on; default the company's default VCS connection (400 when it has none). A connection of another company answers 404.",
        "schema": {
          "$ref": "#/components/schemas/ObjectId"
        }
      },
      "VCSProjectId": {
        "name": "pid",
        "in": "path",
        "required": true,
        "description": "The repository's ID on the VCS (a project's `repo_id`), not Merge Pilot's project ID.",
        "schema": {
          "type": "string"
        }
      },
      "VCSGroupId": {
        "name": "gid",
        "in": "path",
        "required": true,
        "description": "The group's ID on the VCS (`id` from `GET /vcs-ops/groups`).",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "Message": {
        "description": "A confirmation message.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Envelope"
                },
                {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "AnyObject": {
        "description": "The data (shape defined by the server; see the UI for its use).",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Envelope"
                },
                {
                  "type": "object",
                  "properties": {
                    "data": {}
                  }
                }
              ]
            }
          }
        }
      },
      "PendingReview": {
        "description": "Four-eyes review is on for this company: the change was queued and\napplies when a second authorized person approves it.\n",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Envelope"
                },
                {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "pending",
                        "change"
                      ],
                      "properties": {
                        "pending": {
                          "type": "boolean",
                          "const": true
                        },
                        "change": {
                          "$ref": "#/components/schemas/ConfigChange"
                        }
                      }
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid input (bad JSON, missing required field, bad ID, validation failed).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Not signed in, or the session / API token is invalid, expired or revoked.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The role does not allow this (`your role does not allow this`), a\nread-only role tried to change something (`this role can only read`),\nCSRF header missing, an API token on a session-only endpoint, or a\npassword change is pending (`error.code = password_change_required`).\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found (also for resources of another company).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Conflict": {
        "description": "Conflicts with the current state (concurrent edit, already decided, in use).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "BadGateway": {
        "description": "The VCS or tracker call failed. A VCS's refusal is given in its own words (\"GitHub answered 403: …\"), never with the API call that failed. When the VCS refuses Merge Pilot's own account (401): \"Merge Pilot's account was refused by GitLab; check the connection\".",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "ConnectionOff": {
        "description": "The connection is turned off (`this connection is turned off: ask a company admin`): every change through it is refused, company admins included, but leaving a repository or group, cancelling an invitation and revoking a token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "NotImplemented": {
        "description": "The connection's VCS does not support this operation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "VCSRateLimited": {
        "description": "The VCS's API rate limit is reached (\"GitLab's API rate limit is reached: try again in N seconds\").",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before trying again.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "ObjectId": {
        "type": "string",
        "pattern": "^[0-9a-f]{24}$",
        "description": "24-hex-character ID.",
        "examples": [
          "65f1c2a9e4b0a1b2c3d4e5f6"
        ]
      },
      "Envelope": {
        "type": "object",
        "required": [
          "success"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "data": {
            "description": "The payload."
          },
          "meta": {
            "description": "Pagination or other metadata (present on some answers)."
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "message"
            ],
            "properties": {
              "message": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "description": "Stable machine-readable reason, for errors the client must act\non. Sent only with these errors: `password_change_required`\n(403, a password change is pending: only the own password\nchange, logout and reading the own account work),\n`assignee_immutable` (422 from assigning a tracker issue of a\nproject in VCS mode, whose assignee is set when the change\napproval is created), and, in the web interface's sign-in\nflow, `session_ended` (the session may not continue, and the\nmessage says why) and the account link refusals\n(`invalid_state`, `account_disabled`, `link_no_company`,\n`link_other_company`, `already_linked`, `server_error`), and\n`link_required` (400 from an operation on a VCS connection the\ncaller has not linked their account on: \"Link your GitLab\naccount in My profile to use this.\").\n",
                "enum": [
                  "password_change_required",
                  "assignee_immutable",
                  "session_ended",
                  "invalid_state",
                  "account_disabled",
                  "link_no_company",
                  "link_other_company",
                  "already_linked",
                  "server_error",
                  "link_required"
                ]
              },
              "field_key": {
                "type": "string",
                "description": "The field the error is about, sent with `assignee_immutable` (`assignee`)."
              }
            }
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "total_pages": {
            "type": "integer",
            "description": "Present on some lists only."
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "username": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "platform_admin",
              "company_admin",
              "policy_manager",
              "auditor",
              "user"
            ]
          },
          "auth_source": {
            "type": "string",
            "description": "Sign-in method that created the account."
          },
          "active": {
            "type": "boolean"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "language": {
            "type": "string"
          },
          "vcs_identities": {
            "type": "array",
            "description": "Accounts linked on VCS connections (needed to vote).",
            "items": {
              "type": "object",
              "properties": {
                "connection_id": {
                  "$ref": "#/components/schemas/ObjectId"
                },
                "user_id": {
                  "type": "string"
                },
                "username": {
                  "type": "string"
                }
              }
            }
          },
          "sso_identities": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "sso_invite": {
            "type": "object",
            "description": "An invitation to link an identity provider account at the next sign-in with it (POST /users/{id}/sso-invite).",
            "properties": {
              "provider_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "email": {
                "type": "string"
              },
              "invited_by": {
                "type": "string"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "role_source": {
            "type": "string",
            "enum": [
              "idp",
              "ldap"
            ],
            "description": "Set when the role comes from the person's groups at every sign-in, an identity provider's (idp) or the company directory's (ldap); the role cannot be changed in Merge Pilot then. A directory turned off or without a role mapping gives the role back."
          },
          "tracker_account": {
            "type": "string"
          },
          "must_change_password": {
            "type": "boolean"
          },
          "last_login": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UserEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/User"
              }
            }
          }
        ]
      },
      "DirectoryEntry": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "username": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "description": "Empty for auditors."
          },
          "role": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "linked_vcs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Linked VCS usernames; without one a person is not assigned change approvals and cannot vote."
          }
        }
      },
      "MergeRequest": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "repo_id": {
            "type": "string"
          },
          "mr_number": {
            "type": "string"
          },
          "vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "tracker_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "title": {
            "type": "string"
          },
          "source_branch": {
            "type": "string"
          },
          "target_branch": {
            "type": "string"
          },
          "author": {
            "type": "string",
            "description": "VCS username of the author."
          },
          "author_id": {
            "type": "string",
            "description": "VCS account ID of the author; it decides who opened the MR (a renamed account keeps it)."
          },
          "state": {
            "type": "string",
            "description": "`opened`, `merged`, `closed`, `out_of_scope`, ..."
          },
          "closed_reason": {
            "type": "string",
            "enum": [
              "deleted"
            ],
            "description": "Set when a closed merge request was deleted on the VCS (it answered 404 for it while its repository was there): its undecided change approval was cancelled."
          },
          "web_url": {
            "type": "string"
          },
          "head_sha": {
            "type": "string"
          },
          "policy": {
            "$ref": "#/components/schemas/PolicyRef"
          },
          "decision": {
            "$ref": "#/components/schemas/Decision"
          },
          "eligible_approvers": {
            "type": "integer",
            "description": "Who may approve (without the author): people of the company who linked their VCS account and hold an approver role on the repository (or fill the policy's pool or code owners); a decision in the tracker counts from them only. Absent when not counted (lenient tracker approvals without a pool)."
          },
          "viewer": {
            "type": "object",
            "readOnly": true,
            "description": "What the reader may do on the merge request (only on the merge request itself, when it has a change approval).",
            "properties": {
              "may_vote": {
                "type": "boolean",
                "description": "They may approve or reject the change approval in Merge Pilot now, as the vote would be judged: their approver role, a read-only role (auditor: never), a service token (never), the merge request's state and an approval already complete included."
              },
              "why_not_vote": {
                "type": "string",
                "description": "Why not, when they may not."
              },
              "may_approve": {
                "type": "boolean",
                "description": "They may approve it too; may_vote alone means reject only (a committer the policy does not let approve)."
              },
              "why_not_approve": {
                "type": "string",
                "description": "Why they may not approve, when they may only reject."
              },
              "may_take": {
                "type": "boolean",
                "description": "They may take the change approval (they may approve it, here or in the tracker; only while the merge request is open and the change approval undecided)."
              }
            }
          },
          "approvers_short": {
            "type": "boolean",
            "description": "No approval group can be met by the people who may approve."
          },
          "draft": {
            "type": "boolean"
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "author_bot": {
            "type": "boolean"
          },
          "risk_assessment": {
            "$ref": "#/components/schemas/RiskAssessment"
          },
          "issue_tracker": {
            "$ref": "#/components/schemas/MRIssueTracker"
          },
          "approval": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MRApproval"
              }
            ],
            "description": "The approval groups and votes. Before the first vote, the merge request itself (GET) shows the policy's groups at its risk level with no approver yet; the record stores them with the first vote."
          },
          "secret_scan": {
            "type": "object",
            "description": "Secret scan summary (status, findings, total_count, stored_count, by_severity, head_sha, ...). total_count is every finding of the scan; by_severity counts them by severity; stored_count those kept in findings (at most the company's `scanning.secrets.max_findings`). Each finding has a `fingerprint` (a hash of its rule and value, never the value) an exception accepts it by. A failed scan (`status: failed`) says in error what could not be read and from where, and whether Merge Pilot tries again by itself.",
            "additionalProperties": true
          },
          "sca_scan": {
            "type": "object",
            "description": "Dependency/licence scan summary (status, result_id, severity counts, licence findings, ...). advisories lists every introduced advisory (beyond the listed limit too) so an exception recounts from all of them. lookup_failed counts new versions whose licence and package data deps.dev could not give (lookup_error says why): the licence and package health controls fail on it; failed_at starts the retry pause of `sca.on_error: retry`. sources is the dependency source check (absent: not run for this scan).",
            "additionalProperties": true,
            "properties": {
              "sources": {
                "$ref": "#/components/schemas/MRSourceScan"
              }
            }
          },
          "signatures": {
            "type": "object",
            "description": "Commit signatures at head_sha (signature check): checked, unsigned (`[{sha, name, email, username, reason}]`), error when they could not all be read.",
            "additionalProperties": true
          },
          "code_owners": {
            "type": "object",
            "description": "Code owners of the changed files at head_sha (policies with a code owners requirement): target_branch, file, sets (`[{key, section, pattern, owners, files, count}]`), skipped owners with why, error.",
            "additionalProperties": true
          },
          "workflow_scan": {
            "$ref": "#/components/schemas/MRWorkflowScan"
          },
          "image_scan": {
            "$ref": "#/components/schemas/MRImageScan"
          },
          "iac_scan": {
            "$ref": "#/components/schemas/MRIaCScan"
          },
          "pipelines": {
            "type": "array",
            "description": "CI runs. app is who reported the run (github-actions, gitlab, status for a commit status or GitLab external pipeline, or a GitHub App's slug); path is a GitHub workflow run's workflow file.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "emergency": {
            "type": "object",
            "description": "Who declared the merge request an emergency, while an emergency policy covers it.",
            "properties": {
              "policy": {
                "type": "string"
              },
              "label": {
                "type": "string",
                "description": "The label the policy matches on; empty when it matches on something else (then by is the author)."
              },
              "by": {
                "type": "string"
              },
              "by_id": {
                "type": "string"
              },
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "is_author": {
                "type": "boolean"
              },
              "error": {
                "type": "string",
                "description": "Who declared it could not be read."
              }
            }
          },
          "merged_by": {
            "type": "string"
          },
          "merged_without_approval": {
            "type": "boolean"
          },
          "committers": {
            "type": "array",
            "description": "Git authors and committers of the MR's commits.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "email": {
                  "type": "string"
                },
                "username": {
                  "type": "string"
                },
                "id": {
                  "type": "string",
                  "description": "VCS account ID",
                  "when the VCS links the commit to one.": null
                },
                "unmatched": {
                  "type": "boolean",
                  "description": "No person of the company has this e-mail or VCS account."
                }
              }
            }
          },
          "sod_flags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Separation-of-duties exceptions."
          },
          "close_attempt": {
            "type": "object",
            "description": "The last time its policy had the merge request closed.",
            "properties": {
              "head_sha": {
                "type": "string"
              },
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "error": {
                "type": "string",
                "description": "Why the VCS refused the close (tried again after a pause)."
              }
            }
          },
          "merged_in_freeze": {
            "type": "string",
            "description": "The change freeze the merge request was merged in",
            "against it.": null
          },
          "would_have_held_in_freeze": {
            "type": "string",
            "description": "Watched merge requests: the change freeze it was merged in, which would have held it under change management."
          },
          "sod_violation": {
            "type": "boolean"
          },
          "approval_revoked_after_merge": {
            "type": "boolean"
          },
          "merged_at": {
            "type": "string",
            "format": "date-time"
          },
          "merged_commit_sha": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PolicyRef": {
        "type": "object",
        "description": "The policy version that covers the merge request.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "name": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "change_type": {
            "type": "string",
            "enum": [
              "standard",
              "normal",
              "emergency"
            ]
          },
          "priority": {
            "type": "string"
          },
          "default": {
            "type": "boolean"
          },
          "deny": {
            "type": "boolean",
            "description": "The policy refuses what it covers (a Refuse policy)."
          },
          "matched_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Decision": {
        "type": "object",
        "description": "The latest evaluation against the policy, for the head commit it saw.",
        "properties": {
          "head_sha": {
            "type": "string"
          },
          "target_branch": {
            "type": "string",
            "description": "The branch the merge request targeted when decided; an approval is for that branch only."
          },
          "gate": {
            "type": "string",
            "enum": [
              "approved",
              "pending",
              "blocked"
            ]
          },
          "controls": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ControlResult"
            }
          },
          "evaluated_at": {
            "type": "string",
            "format": "date-time"
          },
          "gate_set": {
            "type": "boolean",
            "description": "The VCS has this decision's gate."
          },
          "freeze_releasable": {
            "type": "boolean",
            "description": "A change freeze holds the change and its policy lets someone release it (POST /merge-requests/{id}/freeze-release)."
          }
        }
      },
      "EmergencyRules": {
        "type": "object",
        "description": "Who may declare a change an emergency: who added the label an emergency policy matches on (else the author). Nothing set: anyone who may label it. A policy's own rules replace the company's.",
        "properties": {
          "pool_id": {
            "type": "string",
            "description": "Only people of this approver pool."
          },
          "not_author": {
            "type": "boolean",
            "description": "The author may not declare their own change one."
          },
          "quota_count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000,
            "description": "Emergencies per repository in quota_days (0 none)."
          },
          "quota_days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365
          }
        }
      },
      "ControlResult": {
        "type": "object",
        "properties": {
          "control": {
            "type": "string",
            "description": "policy, work_items, code_review, ci, secret_scan, sca, licenses, package_health, sources, workflows, signatures, images, iac, risk, freeze or approval."
          },
          "status": {
            "type": "string",
            "enum": [
              "passed",
              "pending",
              "failed",
              "skipped"
            ]
          },
          "blocking": {
            "type": "boolean",
            "description": "The control can hold the merge gate (report-only controls cannot)."
          },
          "reason": {
            "type": "string"
          }
        }
      },
      "RiskAssessment": {
        "type": "object",
        "properties": {
          "risk_level": {
            "type": "string"
          },
          "risk_score": {
            "type": "number"
          },
          "change_window_score": {
            "type": "number"
          },
          "criticality_score": {
            "type": "number"
          },
          "footprint_score": {
            "type": "number"
          },
          "mr_size_score": {
            "type": "number"
          },
          "added_lines": {
            "type": "integer"
          },
          "deleted_lines": {
            "type": "integer"
          },
          "changed_files": {
            "type": "integer"
          },
          "footprint_category": {
            "type": "string"
          },
          "in_blackout": {
            "type": "boolean"
          },
          "blocked": {
            "type": "boolean"
          },
          "block_reason": {
            "type": "string"
          },
          "allowed_by": {
            "type": "string"
          },
          "allowed_at": {
            "type": "string",
            "format": "date-time"
          },
          "allow_reason": {
            "type": "string"
          },
          "assessed_at": {
            "type": "string",
            "format": "date-time"
          },
          "head_sha": {
            "type": "string"
          },
          "diff_cut": {
            "type": "boolean",
            "description": "The VCS listed only part of the change."
          },
          "counted_as": {
            "type": "string",
            "description": "The level a cut-short change is counted as (`scanning.coverage.unreadable_risk`)."
          },
          "unknown": {
            "type": "boolean"
          }
        }
      },
      "MRIssueTracker": {
        "type": "object",
        "description": "The change approval (change ticket) of the merge request.",
        "properties": {
          "change_approval_key": {
            "type": "string"
          },
          "change_approval_url": {
            "type": "string"
          },
          "change_approval_status": {
            "type": "string",
            "description": "`open`, `approved`, `rejected`, ..."
          },
          "change_approval_assignee": {
            "type": "string",
            "description": "The assignee as the tracker knows them (its account: an email, a login or a Merge Pilot user name)."
          },
          "decided_in_tracker_only": {
            "type": "boolean",
            "readOnly": true,
            "description": "The company decides this change approval in its tracker (Jira) only (`tracker_decisions_only`): no votes in Merge Pilot. Only on the merge request itself."
          },
          "change_approval_assignee_name": {
            "type": "string",
            "readOnly": true,
            "description": "The Merge Pilot person behind the assignee (display name, else user name), when one is found as votes are; only on the merge request itself."
          },
          "assignment_problem": {
            "type": "string",
            "description": "Why the change approval has no assignee: nobody may take it."
          },
          "change_approval_created_at": {
            "type": "string",
            "format": "date-time"
          },
          "change_approval_commit_sha": {
            "type": "string",
            "description": "Head commit the change approval covers; approval only holds while the MR head is this commit."
          },
          "change_approval_history": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "commit_sha": {
                  "type": "string"
                },
                "outcome": {
                  "type": "string",
                  "enum": [
                    "superseded",
                    "reopened",
                    "lost"
                  ]
                },
                "reason": {
                  "type": "string"
                },
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "tracker_connection_id": {
                  "$ref": "#/components/schemas/ObjectId"
                },
                "sync_move": {
                  "type": "string",
                  "enum": [
                    "approved",
                    "rejected",
                    "merged",
                    "cancelled",
                    "reopened"
                  ],
                  "description": "The move this retired change approval still owes the tracker, retried to the status the settings name at the time: its cancel when superseded (cancelled), or the move it owed when it was replaced."
                },
                "sync_error": {
                  "type": "string",
                  "description": "Why that move failed."
                },
                "sync_error_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "work_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "provider": {
                  "type": "string"
                },
                "connection_id": {
                  "$ref": "#/components/schemas/ObjectId"
                },
                "key": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "work_item_problems": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "change_approval_error": {
            "type": "string"
          },
          "sync_error": {
            "type": "string"
          },
          "sync_move": {
            "type": "string",
            "enum": [
              "approved",
              "rejected",
              "merged",
              "cancelled",
              "reopened"
            ],
            "description": "What the failed move was for. It is tried again before decisions are read from the tracker, to the status the connection's settings (or the tracker's decision states) name at the time: a corrected setting is followed, and a status no longer set means nothing is owed."
          },
          "review_due_at": {
            "type": "string",
            "format": "date-time"
          },
          "decided_after_merge": {
            "type": "boolean"
          },
          "decided_by": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "MRApproval": {
        "type": "object",
        "description": "Approval state of the current change approval.",
        "properties": {
          "groups": {
            "type": "array",
            "description": "The policy's approval groups at the MR's risk level; the change approval is approved when any one group is met.",
            "items": {
              "type": "object",
              "properties": {
                "met": {
                  "type": "boolean"
                },
                "requirements": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string",
                        "description": "Pool name (\"\" for the repository's maintainers)."
                      },
                      "required": {
                        "type": "integer"
                      },
                      "approvers": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "votes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApprovalVote"
            }
          },
          "approved": {
            "type": "boolean"
          },
          "approved_by": {
            "type": "string"
          },
          "approved_at": {
            "type": "string",
            "format": "date-time"
          },
          "fatigue": {
            "type": "array",
            "description": "Approval concentration warnings raised by this change's approvers, one per approver; a warning once raised stays.",
            "items": {
              "type": "object",
              "properties": {
                "approver": {
                  "type": "string"
                },
                "recent_count": {
                  "type": "integer",
                  "description": "Changes the approver approved in the lookback, this one counted once."
                },
                "lookback_days": {
                  "type": "integer"
                },
                "threshold": {
                  "type": "integer"
                },
                "warning": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      },
      "ApprovalVote": {
        "type": "object",
        "properties": {
          "voter": {
            "type": "string",
            "description": "Whose vote it is (the approver)."
          },
          "user_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "fills": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Requirement IDs this approval counts for."
          },
          "cast_by": {
            "type": "string",
            "description": "The delegate who voted for `voter`, when not the voter."
          },
          "cast_by_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "source": {
            "type": "string",
            "enum": [
              "merge_pilot",
              "tracker"
            ]
          },
          "decision": {
            "type": "string",
            "enum": [
              "approve",
              "reject"
            ]
          },
          "comment": {
            "type": "string"
          },
          "change_approval_key": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MergeRequestEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/MergeRequest"
              }
            }
          }
        ]
      },
      "MergeRequestListEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MergeRequest"
                }
              },
              "meta": {
                "$ref": "#/components/schemas/PaginationMeta"
              }
            }
          }
        ]
      },
      "Project": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "repo_id": {
            "type": "string"
          },
          "vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "name": {
            "type": "string"
          },
          "path_with_namespace": {
            "type": "string"
          },
          "web_url": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "gated",
              "monitor"
            ],
            "description": "gated: under change management; monitor: watched only (nothing is written to the repository)."
          },
          "target_branches": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The project's own target branches (else the company's)."
          },
          "excluded_branches": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Merge requests into these branches are not followed. Where the gate holds such a branch all the same (on GitLab, a wildcard target such as release/* also covers an excluded release/legacy: an approval rule cannot leave one branch out), Merge Pilot approves its merge requests without checking them and says so once on the merge request."
          },
          "vcs_access_lost_at": {
            "type": "string",
            "format": "date-time",
            "description": "When Merge Pilot found it no longer reaches the repository: the GitHub App's access to it was removed, or the VCS answers 404 or 403 for the repository itself. Cleared when it answers again (the access is given back). Take such a repository out with POST /projects/{id}/forget."
          },
          "open_mrs_swept_at": {
            "type": "string",
            "format": "date-time",
            "description": "When its open merge requests were last listed on the VCS (`monitoring.open_mr_sweep_hours`)."
          },
          "push_ignore_list": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Login globs whose pushes are not recorded as direct changes (on top of the company's)."
          },
          "watch_started_at": {
            "type": "string",
            "format": "date-time"
          },
          "backfill": {
            "type": "object",
            "description": "The import of past merge requests when watching started.",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "running",
                  "done",
                  "failed"
                ]
              },
              "imported": {
                "type": "integer"
              },
              "skipped": {
                "type": "integer"
              },
              "error": {
                "type": "string"
              },
              "queued_at": {
                "type": "string",
                "format": "date-time",
                "description": "When the import was asked for."
              }
            }
          },
          "tracker_override": {
            "$ref": "#/components/schemas/TrackerOverride"
          },
          "vcs_settings": {
            "$ref": "#/components/schemas/VCSSettings"
          },
          "sca_exclude": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Manifest path globs the project's analysis skips."
          },
          "cm_setup": {
            "$ref": "#/components/schemas/CMSetup"
          },
          "cm_steps": {
            "type": "object",
            "additionalProperties": {
              "type": "boolean"
            },
            "description": "The setup steps agreed to; setting it up again writes the same."
          },
          "events_warning": {
            "type": "string",
            "description": "What is wrong with the delivery of its events."
          },
          "default_branch": {
            "type": "string"
          },
          "heads_checked_at": {
            "type": "string",
            "format": "date-time",
            "description": "When its watched branches' heads were last checked."
          },
          "protection": {
            "type": "object",
            "description": "What the last protection check found (gated projects).",
            "properties": {
              "weakened": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "What lets changes skip the merge gate."
              },
              "checked_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "VulnFinding": {
        "type": "object",
        "description": "One advisory affecting one package version on a project's default branch.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "project_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "repo_id": {
            "type": "string"
          },
          "project_path": {
            "type": "string"
          },
          "ecosystem": {
            "type": "string"
          },
          "package": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "manifests": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "direct": {
            "type": "boolean",
            "description": "The project names it itself (absent: not known)."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Dependency groups (`dev`, `optional`); none: it ships with the project."
          },
          "advisory": {
            "type": "object",
            "additionalProperties": true,
            "description": "id, aliases, summary, severity, fixed_in, url, malicious, kev (exploited in the wild, CISA KEV), epss (probability of exploitation in 30 days, FIRST EPSS)."
          },
          "has_fix": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "fixed"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "analysis",
              "merge",
              "advisory",
              "direct"
            ]
          },
          "first_seen_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_seen_at": {
            "type": "string",
            "format": "date-time"
          },
          "fixed_at": {
            "type": "string",
            "format": "date-time"
          },
          "introduced_by": {
            "$ref": "#/components/schemas/FindingMR"
          },
          "fixed_by": {
            "$ref": "#/components/schemas/FindingMR"
          },
          "introduced_by_change": {
            "$ref": "#/components/schemas/FindingChange"
          },
          "fixed_by_change": {
            "$ref": "#/components/schemas/FindingChange"
          },
          "exception_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "baseline": {
            "type": "boolean",
            "description": "Found by the project's first analysis (its baseline): never new."
          }
        }
      },
      "FindingMR": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "number": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "merged_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "FindingChange": {
        "type": "object",
        "description": "A direct change (pushed without a merge request) that brought a finding in or removed it.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId",
            "description": "The recorded direct change; absent when the company does not record direct changes (the push is named by branch and commit only)."
          },
          "branch": {
            "type": "string"
          },
          "after": {
            "type": "string",
            "description": "The branch's head after the change."
          },
          "pusher": {
            "type": "string"
          }
        }
      },
      "DirectChange": {
        "type": "object",
        "description": "A change made to a watched branch that did not (all) come through a merge request.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "project_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "repo_id": {
            "type": "string"
          },
          "project_path": {
            "type": "string"
          },
          "project_url": {
            "type": "string"
          },
          "branch": {
            "type": "string"
          },
          "project_mode": {
            "type": "string",
            "enum": [
              "gated",
              "monitor"
            ]
          },
          "before": {
            "type": "string"
          },
          "after": {
            "type": "string",
            "description": "All zeros: the branch was deleted."
          },
          "forced": {
            "type": "boolean",
            "description": "The push rewrote the branch's history."
          },
          "created": {
            "type": "boolean"
          },
          "deleted": {
            "type": "boolean"
          },
          "pusher": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "username": {
                "type": "string"
              }
            },
            "description": "Empty when the head check found it."
          },
          "via": {
            "type": "string",
            "enum": [
              "push",
              "head_check"
            ]
          },
          "commits": {
            "type": "array",
            "description": "The newest 50 commits (never their content).",
            "items": {
              "type": "object",
              "properties": {
                "sha": {
                  "type": "string"
                },
                "author": {
                  "type": "string"
                },
                "author_email": {
                  "type": "string"
                },
                "title": {
                  "type": "string",
                  "description": "The first line of the message."
                },
                "files": {
                  "type": "integer",
                  "description": "Files changed (-1: not known)."
                },
                "manifests": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "mr": {
                  "$ref": "#/components/schemas/ChangeMR"
                }
              }
            }
          },
          "commit_count": {
            "type": "integer"
          },
          "direct_commits": {
            "type": "integer",
            "description": "Commits that did not come through a merge request change management approved."
          },
          "mrs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChangeMR"
            }
          },
          "manifests_changed": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "class": {
            "type": "string",
            "enum": [
              "direct",
              "mixed",
              "ignored"
            ]
          },
          "violation": {
            "type": "boolean",
            "description": "The project is under change management."
          },
          "would_have_blocked": {
            "type": "boolean",
            "description": "The project is watched; change management would have stopped it."
          },
          "refreshed": {
            "type": "boolean",
            "description": "The vulnerability inventory was refreshed for it."
          },
          "detected_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ChangeMR": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "unapproved": {
            "type": "boolean",
            "description": "Merged into a gated branch without change management's approval (or never seen): its commits count as direct."
          }
        }
      },
      "DirectChangeSummary": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "by_class": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "violations": {
            "type": "integer"
          },
          "would_have_blocked": {
            "type": "integer"
          },
          "forced": {
            "type": "integer"
          },
          "deleted": {
            "type": "integer"
          },
          "top_pushers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          },
          "top_projects": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "VulnSummary": {
        "type": "object",
        "properties": {
          "open": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Open findings without an exception",
            "by severity.": null
          },
          "open_total": {
            "type": "integer"
          },
          "excepted": {
            "type": "integer"
          },
          "with_fix": {
            "type": "integer"
          },
          "new_7_days": {
            "type": "integer",
            "description": "Findings first seen in the last 7 days and still open without an exception, not a project's baseline."
          },
          "new_30_days": {
            "type": "integer",
            "description": "Findings first seen in the last 30 days and still open without an exception, not a project's baseline."
          },
          "fixed_30_days": {
            "type": "integer"
          },
          "projects_with_fix": {
            "type": "integer",
            "description": "Projects with an open finding (without an exception) that has a fix."
          },
          "top_packages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "ecosystem": {
                  "type": "string"
                },
                "package": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "worst": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "VulnExceptionInput": {
        "type": "object",
        "required": [
          "reason",
          "expires_at"
        ],
        "description": "What the exception accepts, by `kind`: an advisory (absent or empty: `advisory_id` required, `state` too), a secret finding (`secret`: `fingerprint`, the finding's), a dependency's license (`license`: `package`, and `license` to narrow it to one license expression), or a package health finding (`package`: `package`, and `version` to narrow it to one version; a leading v is ignored). Merge requests are no longer held for what it accepts.",
        "properties": {
          "project_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "kind": {
            "type": "string",
            "enum": [
              "",
              "secret",
              "license",
              "package"
            ]
          },
          "advisory_id": {
            "type": "string",
            "description": "Advisory exceptions: matched against advisory IDs and aliases."
          },
          "fingerprint": {
            "type": "string",
            "description": "Secret exceptions."
          },
          "license": {
            "type": "string",
            "description": "License exceptions: one license expression (empty: any)."
          },
          "version": {
            "type": "string",
            "description": "Package exceptions: one version (empty: any)."
          },
          "ecosystem": {
            "type": "string"
          },
          "package": {
            "type": "string",
            "description": "Only this package (empty: any; required for license and package exceptions)."
          },
          "state": {
            "type": "string",
            "enum": [
              "accepted",
              "not_affected"
            ]
          },
          "reason": {
            "type": "string",
            "maxLength": 2000
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "VulnException": {
        "allOf": [
          {
            "$ref": "#/components/schemas/VulnExceptionInput"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "company_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "created_by": {
                "type": "string"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "revoked_at": {
                "type": "string",
                "format": "date-time"
              },
              "revoked_by": {
                "type": "string"
              },
              "project": {
                "type": "object",
                "description": "In a list, the project of an exception for one project (absent when the project was removed).",
                "properties": {
                  "repo_id": {
                    "type": "string"
                  },
                  "vcs_connection_id": {
                    "$ref": "#/components/schemas/ObjectId"
                  },
                  "path_with_namespace": {
                    "type": "string"
                  }
                }
              }
            }
          }
        ]
      },
      "MonitoringReport": {
        "type": "object",
        "properties": {
          "since": {
            "type": "string",
            "format": "date-time"
          },
          "until": {
            "type": "string",
            "format": "date-time"
          },
          "drafts": {
            "type": "boolean"
          },
          "truncated": {
            "type": "boolean",
            "description": "More than 5000 merge requests of the watched repositories in scope; the newest 5000 are counted."
          },
          "merge_requests": {
            "type": "integer"
          },
          "unmatched": {
            "type": "integer",
            "description": "Merge requests no policy matched (draft policies without a default policy); left out of every count and of the CSV."
          },
          "merged": {
            "type": "integer"
          },
          "approved": {
            "type": "integer"
          },
          "pending": {
            "type": "integer"
          },
          "blocked": {
            "type": "integer"
          },
          "needs_change_approval": {
            "type": "integer"
          },
          "would_have_blocked": {
            "type": "integer",
            "description": "Merges the report's policies would hold, evaluated now."
          },
          "held_at_merge": {
            "type": "integer",
            "description": "Merges recorded as held when they merged (as each merge request shows)."
          },
          "direct_changes": {
            "type": "integer",
            "description": "Changes pushed to the watched branches without a merge request."
          },
          "change_approvals_per_week": {
            "type": "number"
          },
          "merges_per_week": {
            "type": "number"
          },
          "lead_time_hours": {
            "type": "number",
            "description": "Median",
            "opened to merged.": null
          },
          "policies": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "controls": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "projects": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "findings": {
            "type": "object",
            "additionalProperties": true
          },
          "risk": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          }
        }
      },
      "TrackerOverride": {
        "type": "object",
        "properties": {
          "project_key": {
            "type": "string"
          },
          "issue_type": {
            "type": "string"
          },
          "link_type": {
            "type": "string"
          }
        }
      },
      "ProjectEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Project"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        ]
      },
      "ProjectAnalysis": {
        "type": "object",
        "description": "A summary of one analysis of a project's default branch (dependencies, vulnerabilities, licenses); what it found is in its details.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "project_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "repo_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "failed"
            ]
          },
          "ref": {
            "type": "string",
            "description": "The branch analysed."
          },
          "commit_sha": {
            "type": "string",
            "description": "Its head when analysed."
          },
          "triggered_by": {
            "type": "string",
            "description": "Who or what started it: the username, `merge <number>` or `direct change <sha>`."
          },
          "cause": {
            "type": "string",
            "enum": [
              "analysis",
              "merge",
              "direct"
            ],
            "description": "merge: a merge request merged into the default branch (`mr`); direct: a change pushed to it without one (`change`); absent or analysis: started by hand."
          },
          "mr": {
            "$ref": "#/components/schemas/FindingMR"
          },
          "change": {
            "$ref": "#/components/schemas/FindingChange"
          },
          "manifests_read": {
            "type": "integer",
            "description": "Manifests read from the VCS; the others were unchanged since the last analysis and taken from it."
          },
          "new_findings": {
            "type": "integer",
            "description": "Findings of the vulnerability inventory this analysis opened (none for the project's first analysis: it is the baseline)."
          },
          "fixed_findings": {
            "type": "integer",
            "description": "Findings of the vulnerability inventory this analysis closed."
          },
          "manifests_found": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "total_deps": {
            "type": "integer"
          },
          "total_vulns": {
            "type": "integer"
          },
          "total_license_entries": {
            "type": "integer"
          },
          "unique_license_exprs": {
            "type": "integer"
          },
          "unique_license_atoms": {
            "type": "integer"
          },
          "severity_counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Vulnerabilities per severity."
          },
          "license_expr_summary": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Dependencies per license expression."
          },
          "license_atom_summary": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Dependencies per single license."
          },
          "truncation_reasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Why the analysis could not read everything (manifest limit, a truncated tree, an unreadable manifest), as `reason` or `reason:number`. `tree_truncated:5000` names where GitLab's listing stops; GitHub cuts its listing without saying where (`tree_truncated`)."
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          },
          "duration_ms": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          },
          "error_code": {
            "type": "string",
            "enum": [
              "TRANSIENT",
              "PERMANENT"
            ],
            "description": "TRANSIENT: may be retried at once."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ProjectAnalysisEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ProjectAnalysis"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        ]
      },
      "ProjectAnalysisDetail": {
        "type": "object",
        "description": "One kind of what an analysis found; only the array of its `type` is present.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "analysis_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "type": {
            "type": "string",
            "enum": [
              "deps",
              "vulns",
              "licenses"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "dependencies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SCADependency"
            }
          },
          "vulnerabilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SCAVulnerability"
            }
          },
          "licenses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LicenseEntry"
            }
          }
        }
      },
      "SCADependency": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "ecosystem": {
            "type": "string"
          },
          "manifest": {
            "type": "string"
          },
          "purl": {
            "type": "string"
          },
          "unpinned": {
            "type": "boolean",
            "description": "A requirement (version range)",
            "not looked up for advisories.": null
          },
          "direct": {
            "type": "boolean",
            "description": "The project names it itself (absent: the manifest does not say)."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Dependency groups (`dev`, `optional`); none: it ships with the project."
          }
        }
      },
      "SCAVulnerability": {
        "type": "object",
        "description": "One advisory affecting one package version.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The advisory ID."
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "package": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "ecosystem": {
            "type": "string"
          },
          "fixed_in": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "malicious": {
            "type": "boolean"
          },
          "kev": {
            "type": "boolean",
            "description": "Exploited in the wild (CISA KEV)."
          },
          "epss": {
            "type": "number",
            "description": "The probability of exploitation in the next 30 days (FIRST EPSS)."
          },
          "manifests": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The files the package version is in."
          },
          "excepted_by": {
            "$ref": "#/components/schemas/ObjectId",
            "description": "The vulnerability exception it falls under (it does not hold the merge)."
          }
        }
      },
      "LicenseEntry": {
        "type": "object",
        "description": "The licenses found for one dependency.",
        "properties": {
          "package": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "ecosystem": {
            "type": "string"
          },
          "licenses": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of non-standard licenses."
          },
          "status": {
            "type": "string",
            "enum": [
              "found",
              "not_found",
              "unsupported",
              "unpinned",
              "failed"
            ],
            "description": "How the license lookup went."
          },
          "manifest": {
            "type": "string"
          }
        }
      },
      "PolicyInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "description": "A change policy as sent on create/update. On create `vcs_connection_id`\nis required; on update it is ignored and `version` must equal the\ncurrent version.\n",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "version": {
            "type": "integer"
          },
          "active": {
            "type": "boolean"
          },
          "match": {
            "$ref": "#/components/schemas/PolicyMatch"
          },
          "deny": {
            "type": "boolean",
            "description": "Refuse every matching merge request."
          },
          "change_type": {
            "type": "string",
            "enum": [
              "standard",
              "normal",
              "emergency"
            ],
            "default": "normal"
          },
          "emergency": {
            "$ref": "#/components/schemas/EmergencyRules"
          },
          "priority": {
            "type": "string"
          },
          "criticality": {
            "type": "string",
            "enum": [
              "",
              "critical",
              "high",
              "medium",
              "low",
              "none"
            ]
          },
          "controls": {
            "$ref": "#/components/schemas/PolicyControls"
          },
          "on_new_commits": {
            "type": "string",
            "enum": [
              "new_change_approval",
              "reopen_change_approval",
              "keep",
              "keep_if_diff_unchanged"
            ],
            "default": "new_change_approval",
            "description": "`keep_if_diff_unchanged`: the approval stays while the lines the change adds and removes are the ones approved (a rebase, a merge of the target branch); any edit, or a diff that cannot be compared (binary files, no diff from the VCS), opens a new change approval."
          },
          "on_fail": {
            "type": "string",
            "enum": [
              "block",
              "close"
            ],
            "default": "block"
          }
        }
      },
      "Policy": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PolicyInput"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "company_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "order": {
                "type": "integer"
              },
              "default": {
                "type": "boolean",
                "description": "The catch-all policy (always last, always active, cannot be deleted)."
              },
              "updated_by": {
                "type": "string"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "PolicyMatch": {
        "type": "object",
        "description": "Empty conditions match everything; set conditions must all hold.",
        "properties": {
          "target_branches": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source_branches": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "repos": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "paths": {
            "type": "object",
            "properties": {
              "any_of": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "none_of": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "only_in": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "labels": {
            "type": "object",
            "properties": {
              "any_of": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "none_of": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "author": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "any",
                  "human",
                  "bot"
                ],
                "default": "any"
              },
              "usernames": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Limit the match to these authors (\"*\" wildcards, case-insensitive); with kind bot they add accounts the VCS does not flag as bots."
              }
            }
          },
          "max_changed_lines": {
            "type": "integer"
          },
          "max_changed_files": {
            "type": "integer"
          },
          "drafts": {
            "type": "string",
            "enum": [
              "any",
              "exclude",
              "only"
            ],
            "default": "any"
          }
        }
      },
      "PolicyControls": {
        "type": "object",
        "properties": {
          "work_items": {
            "type": "object",
            "properties": {
              "level": {
                "type": "string",
                "enum": [
                  "off",
                  "record",
                  "required"
                ],
                "default": "off"
              },
              "sources": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "commits",
                    "title",
                    "description",
                    "branch"
                  ]
                }
              },
              "required_statuses": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "max_usage": {
                "type": "integer"
              }
            }
          },
          "code_review": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "off",
                "description": "report: shown, never holds the merge."
              },
              "min_approvals": {
                "type": "integer"
              },
              "requested_changes_block": {
                "type": "boolean"
              },
              "min_access": {
                "type": "integer",
                "enum": [
                  0,
                  20,
                  25,
                  30,
                  40,
                  50
                ],
                "description": "Repository role a reviewer needs for their review to count (0: Developer/Write). Bots never count."
              }
            }
          },
          "ci": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "off"
              },
              "checks": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "sources": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "GitHub App slugs whose runs count; empty: GitHub Actions and GitLab pipelines."
              },
              "allow_statuses": {
                "type": "boolean",
                "description": "Commit statuses (GitHub statuses, GitLab external pipelines) count."
              },
              "config_paths": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Files that define CI (empty: .github/workflows/**, .github/actions/**, .gitlab-ci.yml, .gitlab/ci/**)."
              },
              "allow_config_changes": {
                "type": "boolean",
                "description": "Runs count even when the change edits its CI configuration (they do not by default)."
              }
            }
          },
          "secret_scan": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "off"
              },
              "overrides": {
                "type": "object",
                "additionalProperties": true,
                "description": "unscanned_files, inline_allow, scan_texts, custom_rules_enabled, allowed_paths, allowed_rules, on_error, min_severity (low, medium, high, critical)."
              }
            }
          },
          "coverage": {
            "type": [
              "object",
              "null"
            ],
            "description": "The company's scan coverage choices for this policy (`scanning.coverage`; fields left out: the company's).",
            "properties": {
              "incomplete": {
                "type": "string",
                "enum": [
                  "fail",
                  "note"
                ]
              },
              "over_limit": {
                "type": "string",
                "enum": [
                  "fail",
                  "note"
                ]
              },
              "on_error": {
                "type": "string",
                "enum": [
                  "manual",
                  "retry"
                ]
              },
              "unreadable_risk": {
                "type": "string",
                "enum": [
                  "hold",
                  "low",
                  "medium",
                  "high",
                  "critical"
                ]
              }
            }
          },
          "sca": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "off"
              },
              "block_severity": {
                "type": "string",
                "enum": [
                  "low",
                  "medium",
                  "high",
                  "critical"
                ]
              },
              "overrides": {
                "type": "object",
                "additionalProperties": true,
                "description": "allowed_paths, blocked_paths, unknown_severity, on_error, kev (critical|show), epss_hold (0..1, 0 never)."
              }
            }
          },
          "licenses": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "report"
              },
              "overrides": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "signatures": {
            "type": "object",
            "description": "Every commit of the change carries a signature the VCS verified, except those of exempt authors.",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "off"
              },
              "overrides": {
                "type": "object",
                "additionalProperties": true,
                "description": "exempt_authors: logins, e-mails or names (\"*\" wildcards); replaces the company list."
              }
            }
          },
          "workflows": {
            "type": "object",
            "description": "CI configuration check, on GitHub and GitLab: the changed GitHub Actions workflows, or the changed GitLab CI configuration (the project's CI configuration file, YAML files under .gitlab/ci/ and the changed files it includes with include:local), checked by the rules listed in WorkflowFinding.",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "off"
              },
              "min_severity": {
                "type": "string",
                "enum": [
                  "low",
                  "medium",
                  "high"
                ],
                "description": "Only findings of this severity or higher fail the control; lower ones are reported. Absent: every finding fails it."
              },
              "overrides": {
                "type": "object",
                "description": "Each list, when present (also empty), replaces the company's list for this policy; absent or null keeps the company's.",
                "properties": {
                  "pin_allowed": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "description": "owner/* or owner/repo: GitHub actions that need not be pinned to a commit SHA."
                  },
                  "include_allowed": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "description": "GitLab project paths (group/project) or component paths without a version, \"*\" wildcards: their include:project refs and component versions need not be a commit SHA."
                  },
                  "image_allowed": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "description": "Image name prefixes allowed without an @sha256: digest in GitLab CI configuration."
                  }
                }
              }
            }
          },
          "images": {
            "type": "object",
            "description": "Container image scan: the images a change starts referring to (Dockerfile and Containerfile FROM and COPY --from, Kubernetes manifests, Helm values, Compose files) are pulled from their registries and scanned for vulnerable packages. Images the target branch already refers to are not scanned. An image that cannot be scanned fails the control; a reference that depends on a variable or template fails it unless the company or policy sets `unresolved: note`.",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "off"
              },
              "block_severity": {
                "type": "string",
                "enum": [
                  "low",
                  "medium",
                  "high",
                  "critical"
                ],
                "description": "The lowest severity that holds the gate (default high). Vulnerabilities without a fixed version hold it only with `block_unfixed`."
              },
              "overrides": {
                "type": "object",
                "description": "Change the company's image scan settings for this policy. A list, when present (also empty), replaces the company's.",
                "properties": {
                  "block_unfixed": {
                    "type": "boolean"
                  },
                  "unresolved": {
                    "type": "string",
                    "enum": [
                      "fail",
                      "note"
                    ]
                  },
                  "unknown_severity": {
                    "type": "string",
                    "enum": [
                      "show",
                      "high",
                      "block"
                    ]
                  },
                  "skipped_images": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "iac": {
            "type": "object",
            "description": "Infrastructure check: the misconfigurations a change introduces in the infrastructure files it touches (Terraform: the whole directory; a Helm chart: rendered whole; Kubernetes, Dockerfile, CloudFormation, Azure ARM: the file). The files are checked at the head and at the merge base; findings the base already has are not reported. A changed file that cannot be checked (a chart that does not render without its install values, a file that does not parse) fails the control unless the company or policy sets `unchecked: note`.",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "off"
              },
              "min_severity": {
                "type": "string",
                "enum": [
                  "low",
                  "medium",
                  "high",
                  "critical"
                ],
                "description": "Only findings of this severity or higher fail the control (default high); lower ones are reported."
              },
              "overrides": {
                "type": "object",
                "description": "Change the company's infrastructure check settings for this policy. A list, when present (also empty), replaces the company's.",
                "properties": {
                  "unchecked": {
                    "type": "string",
                    "enum": [
                      "fail",
                      "note"
                    ]
                  },
                  "types": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string",
                      "enum": [
                        "terraform",
                        "kubernetes",
                        "helm",
                        "dockerfile",
                        "cloudformation",
                        "azure-arm"
                      ]
                    }
                  },
                  "skipped_checks": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    }
                  },
                  "skipped_paths": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "sources": {
            "type": "object",
            "description": "Dependency sources (runs in the dependency scan): a manifest changed without its lockfile, new or changed lockfile entries fetched from a registry that is not allowed, git, URL and local path dependencies, and pip index options. The rules are listed in SourceFinding.",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "report"
              },
              "overrides": {
                "$ref": "#/components/schemas/SourceOverrides"
              }
            }
          },
          "package_health": {
            "type": "object",
            "description": "New dependency versions published fewer than `min_age_days` days ago, or deprecated by their registry (deps.dev data).",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "report",
                  "block"
                ],
                "default": "report"
              },
              "overrides": {
                "type": "object",
                "additionalProperties": true,
                "description": "min_age_days (0..365, 0 turns the age check off), deprecated (bool)."
              }
            }
          },
          "risk": {
            "type": "object",
            "properties": {
              "block_threshold": {
                "type": "string",
                "description": "A risk level, `never`, or empty for the company setting."
              },
              "release_pool_id": {
                "$ref": "#/components/schemas/ObjectId"
              }
            }
          },
          "freeze": {
            "type": "object",
            "description": "How the company's change freezes treat this policy's changes.",
            "properties": {
              "exempt": {
                "type": "boolean",
                "description": "No freeze holds them, nor raises their risk."
              },
              "release": {
                "type": "boolean",
                "description": "Someone may let one held change go ahead during a freeze (POST /merge-requests/{id}/freeze-release). Default off."
              },
              "release_pool_id": {
                "$ref": "#/components/schemas/ObjectId"
              }
            }
          },
          "approval": {
            "type": "object",
            "properties": {
              "groups": {
                "type": "array",
                "description": "Any one group met approves the change approval; empty means one approval of the repository's maintainers.",
                "items": {
                  "type": "object",
                  "properties": {
                    "requirements": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Generated when empty."
                          },
                          "pool_id": {
                            "$ref": "#/components/schemas/ObjectId"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "code_owners"
                            ],
                            "description": "code_owners: the code owners of the changed files (CODEOWNERS on the target branch) approve, one approval per set of owners; no pool_id, count 1."
                          },
                          "count": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                          },
                          "count_by_risk": {
                            "type": "object",
                            "description": "Per risk level (`low`, `medium`, `high`, `critical`, `unknown`).",
                            "additionalProperties": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              },
              "assignment": {
                "type": "string",
                "enum": [
                  "random",
                  "round_robin",
                  "least_loaded",
                  "unassigned"
                ],
                "default": "random"
              },
              "record_standard": {
                "type": "boolean"
              },
              "review_hours": {
                "type": "integer",
                "description": "Emergency changes' retrospective review deadline."
              },
              "separation": {
                "type": "object",
                "properties": {
                  "committers": {
                    "type": "string",
                    "enum": [
                      "off",
                      "flag",
                      "block"
                    ],
                    "default": "block"
                  },
                  "merger": {
                    "type": "string",
                    "enum": [
                      "off",
                      "flag",
                      "block"
                    ],
                    "default": "off"
                  }
                }
              },
              "no_approver": {
                "type": "string",
                "enum": [
                  "manual",
                  "auto"
                ],
                "description": "What happens to a change approval nobody could be assigned; unset: the company's setting."
              },
              "due_hours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2160,
                "description": "Normal changes only (400 on another change type): how long the change approval may stay open before it is overdue, in hours; unset: the company's `change_approval_due_hours`; 0: no deadline; at most 2160."
              },
              "rejection_mode": {
                "type": "string",
                "enum": [
                  "any",
                  "per_requirement",
                  "majority"
                ],
                "default": "any",
                "description": "When rejections reject the change approval: one rejection (`any`), a rejection in every approval group from one of its approvers (`per_requirement`), or more rejections than approvals (`majority`)."
              },
              "no_withdraw": {
                "type": "boolean",
                "description": "A rejection is final; by default its rejecter or a company administrator may withdraw it before the merge."
              }
            }
          }
        }
      },
      "PolicyVersion": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "policy_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "version": {
            "type": "integer"
          },
          "change": {
            "type": "string",
            "enum": [
              "created",
              "updated",
              "deleted"
            ]
          },
          "snapshot": {
            "$ref": "#/components/schemas/Policy"
          },
          "changed_by": {
            "type": "string"
          },
          "changed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PolicyTemplate": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "additive": {
            "type": "boolean"
          },
          "policies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Policy"
            }
          }
        }
      },
      "Simulation": {
        "type": "object",
        "properties": {
          "policy": {
            "$ref": "#/components/schemas/Policy"
          },
          "gate": {
            "type": "string",
            "enum": [
              "approved",
              "pending",
              "blocked"
            ]
          },
          "controls": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ControlResult"
            }
          },
          "needs_change_approval": {
            "type": "boolean"
          },
          "close": {
            "type": "boolean"
          },
          "summary": {
            "type": "string"
          },
          "facts": {
            "type": "object",
            "additionalProperties": true,
            "description": "The inputs the decision was made from."
          }
        }
      },
      "PolicyListEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Policy"
                }
              }
            }
          }
        ]
      },
      "PolicyWithWarningsEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Policy"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "warnings": {
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          }
        ]
      },
      "CMSetup": {
        "type": "object",
        "description": "What change management wrote to a repository, or (read live) what is in place.",
        "properties": {
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "ok",
                    "failed",
                    "skipped"
                  ]
                },
                "error": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "setup_completed_at": {
            "type": "string",
            "format": "date-time"
          },
          "consented_by": {
            "type": "string",
            "description": "A user ID, or \"connection defaults\" for repositories added automatically."
          },
          "consented_at": {
            "type": "string",
            "format": "date-time"
          },
          "created": {
            "type": "object",
            "description": "What change management created on the repository (not what was there before), for `undo_setup`.",
            "properties": {
              "protected_branches": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "bot_member": {
                "type": "boolean"
              },
              "approval_settings": {
                "type": "object",
                "additionalProperties": {
                  "type": "boolean"
                },
                "description": "GitLab approval setting → its value before Merge Pilot changed it."
              }
            }
          }
        }
      },
      "BulkOperation": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "kind": {
            "type": "string",
            "enum": [
              "watch",
              "add_gated",
              "to_gated",
              "to_watching",
              "unwatch"
            ]
          },
          "steps": {
            "type": "object",
            "additionalProperties": {
              "type": "boolean"
            }
          },
          "gate_open": {
            "type": "boolean"
          },
          "undo_setup": {
            "type": "boolean",
            "description": "to_watching and unwatch - also takes back what change management created."
          },
          "target_branches": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "query": {
            "type": "string",
            "description": "Every repository matching it, found when the operation starts running (total is 0 until then): for watch and add_gated the connection's repositories whose path contains it and not in Merge Pilot yet; for the others the connection's projects whose name or path contains it, in the mode the kind moves from."
          },
          "error": {
            "type": "string",
            "description": "Why the operation did nothing or stopped (its repositories could not be listed, too many match, it could not be queued, it was interrupted, its creator lost access)."
          },
          "created_by": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "created_by_name": {
            "type": "string"
          },
          "consented_by": {
            "type": "string",
            "description": "The user who agreed to the setup steps (the creator, or for a retry the one who agreed in the first operation)."
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "cancelling",
              "cancelled",
              "done",
              "failed"
            ],
            "description": "failed: stopped by an error (see error); its repositories not started are failed too."
          },
          "cancelled_by": {
            "type": "string"
          },
          "paused_until": {
            "type": "string",
            "format": "date-time",
            "description": "A VCS rate limit: no repository starts before it."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "finished_at": {
            "type": "string",
            "format": "date-time"
          },
          "total": {
            "type": "integer"
          },
          "counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Repositories by status."
          }
        }
      },
      "VCSSettings": {
        "type": "object",
        "description": "Who may be assigned and decide change approvals.",
        "properties": {
          "assignee_access_levels": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Exactly these repository roles (vcs access levels of the VCS; GitHub has no 10, GitLab no 25). Empty means Developer, Maintainer and Owner (or the connection's, for a project)."
          },
          "assignee_exclude_list": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "VCS logins never assigned."
          }
        }
      },
      "ApproverPoolInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "user_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ObjectId"
            },
            "description": "Merge Pilot users of the company."
          },
          "vcs_access_levels": {
            "type": "array",
            "items": {
              "type": "integer",
              "enum": [
                10,
                20,
                25,
                30,
                40,
                50
              ]
            },
            "description": "The repository roles members must hold, exactly these (listed people too). Empty means the project's assignee roles."
          },
          "role_members": {
            "type": "boolean",
            "description": "Everyone holding one of the roles belongs to the pool, not only the listed people. A pool needs listed people or this."
          }
        }
      },
      "ApproverPool": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApproverPoolInput"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "company_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "used_by": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The policies of every connection that name the pool."
              },
              "members": {
                "type": "array",
                "description": "The listed users (`user_ids`), named, for everyone who may read the pool.",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "$ref": "#/components/schemas/ObjectId"
                    },
                    "username": {
                      "type": "string"
                    },
                    "display_name": {
                      "type": "string"
                    },
                    "active": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "ApproverPoolVersion": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "pool_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "pool": {
            "$ref": "#/components/schemas/ApproverPool"
          },
          "deleted": {
            "type": "boolean"
          },
          "by": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ApproverPoolEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ApproverPool"
              }
            }
          }
        ]
      },
      "ConfigChange": {
        "type": "object",
        "description": "A control change waiting for (or decided by) a second person.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "kind": {
            "type": "string",
            "description": "`policy_create`, `policy_update`, `policy_delete`, `policy_reorder`, `policy_template`, `pool_save`, `pool_delete`, `risk_config`, ..."
          },
          "target": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "payload": {
            "type": "string",
            "description": "The change as JSON text."
          },
          "requested_by": {
            "type": "string"
          },
          "requested_by_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "applied",
              "rejected",
              "failed"
            ]
          },
          "decided_by": {
            "type": "string"
          },
          "decided_at": {
            "type": "string",
            "format": "date-time"
          },
          "error": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Company": {
        "type": "object",
        "description": "A company. Secret values are never returned; `has_*` flags tell whether one is set.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "branch_patterns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Target branches that are gated, as glob patterns; ~DEFAULT_BRANCH is each repository's default branch (the default for a new company)."
          },
          "dora_production_branches": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The branches whose merges DORA counts as deployments: names and glob patterns as the company's branch patterns (\"release/*\" one level, \"release/**\" any depth, \"hotfix-?\"), ~DEFAULT_BRANCH for each repository's default branch. Empty (the default): each repository's default branch."
          },
          "notifications": {
            "type": "object",
            "properties": {
              "routes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NotificationRoute"
                }
              }
            }
          },
          "scanning": {
            "type": "object",
            "description": "Secret, SCA, licence, package health, CI configuration and dependency source scan settings (`secrets`, `sca`, `licenses`, `packages`, `workflows`, `sources`). `packages.min_age_days`: 0..365 (default 14, 0 off); `packages.deprecated`: default true. `signatures.exempt_authors`: commit authors exempt from the signature check. `sca.kev`: `critical` (default; a vulnerability exploited in the wild counts as critical) or `show`; `sca.epss_hold`: 0..1, hold from that EPSS (0 never). `secrets.on_error` and `sca.on_error`: `manual` (default) or `retry` (a secret or dependency scan that cannot finish, or whose deps.dev lookup failed, is retried after a pause; the image, infrastructure and CI configuration scans follow `coverage.on_error`). The deps.dev lookups are bounded by `sca.external_call_timeout`. `sca.analysis_max_dependencies`: 0..20000 (default 20000), shared among the manifests; past it each analysis looks up the next part. `sca.analysis_timeout_seconds`: 0..600 (default 90), each external lookup of a project analysis and the daily advisory check.",
            "additionalProperties": true,
            "properties": {
              "workflows": {
                "type": "object",
                "description": "CI configuration check allow-lists.",
                "properties": {
                  "pin_allowed": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "description": "owner/* or owner/repo whose GitHub actions need not be pinned to a commit SHA (absent or null: actions/*, github/*; []: none)."
                  },
                  "include_allowed": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "description": "GitLab project paths (group/project) or component paths without a version (\"*\" wildcards) whose includes need not be pinned to a commit SHA (absent, null or []: none)."
                  },
                  "image_allowed": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "description": "Image name prefixes allowed without an @sha256: digest in GitLab CI configuration (absent, null or []: none)."
                  }
                }
              },
              "sources": {
                "$ref": "#/components/schemas/SourceSettings"
              },
              "images": {
                "$ref": "#/components/schemas/ImageScanSettings"
              },
              "iac": {
                "$ref": "#/components/schemas/IaCScanSettings"
              },
              "coverage": {
                "type": "object",
                "description": "What the scans do when they cannot look at all of a change (a policy's `controls.coverage` overrides each field it sets).",
                "properties": {
                  "incomplete": {
                    "type": "string",
                    "enum": [
                      "fail",
                      "note"
                    ],
                    "description": "The VCS listed only part of the changed files: the dependency, license, package health, source, CI configuration, image and infrastructure scans fail (default; final: not retried) or check what was listed and say what was not (`notes`)."
                  },
                  "over_limit": {
                    "type": "string",
                    "enum": [
                      "fail",
                      "note"
                    ],
                    "description": "More images, infrastructure files or dependencies than `max_images`, `max_files`, `max_dependencies`: the scan fails (default; final) or checks the first ones up to the limit and names how many were left out."
                  },
                  "on_error": {
                    "type": "string",
                    "enum": [
                      "manual",
                      "retry"
                    ],
                    "description": "An image, infrastructure or CI configuration scan that could not complete waits for a rescan (default) or is retried after a pause; one failed only by a cut-short list or a limit (`final`) is not retried."
                  },
                  "unreadable_risk": {
                    "type": "string",
                    "enum": [
                      "hold",
                      "low",
                      "medium",
                      "high",
                      "critical"
                    ],
                    "description": "The risk of a change the VCS listed only in part: unknown, held wherever risk holds (default), or counted as that level (`risk_assessment.counted_as`)."
                  }
                }
              },
              "secrets": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "min_severity": {
                    "type": "string",
                    "enum": [
                      "low",
                      "medium",
                      "high",
                      "critical"
                    ],
                    "description": "Findings below it are listed but never hold the merge (default low: every finding). A policy override may set its own."
                  }
                }
              }
            }
          },
          "registries": {
            "type": "array",
            "description": "Sign-ins to the container registries the image scan pulls from (public images need none). Secrets are never returned (`has_secret` instead).",
            "items": {
              "$ref": "#/components/schemas/ContainerRegistry"
            }
          },
          "risk_config": {
            "type": "object",
            "description": "Risk assessment settings (weights, thresholds, change windows, blackout periods, ...). `binary_score`: 0..1, the lowest footprint of a change adding or changing a binary file (default 0.8; 0 off). `size_exclude`: file globs not counted in a change's size (null: the default lockfile and generated-code list; `[]`: every file counts). `change_windows[]`: `day_of_week` (0 Sunday..6), `start_minute` (0..1439) and `end_minute` (0..1440), minutes from midnight in the company's time zone (an end before the start runs past midnight), `score`: the timing score inside the window (omitted: 0.25; 0 allowed). `blackout_periods[]`: `name`, `start`, `end` (wall-clock times), `mode` (`score`, `hold`, `emergency_only`), and optionally `projects` (repository path patterns), `branches` (target branch patterns) and `policies` (policy IDs of the company) that narrow the freeze; each empty: every one. Freeze names are required and unique (case-insensitive): a release names the freeze.",
            "additionalProperties": true
          },
          "approval_fatigue": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "lookback_days": {
                "type": "integer"
              },
              "threshold": {
                "type": "integer"
              }
            }
          },
          "timezone": {
            "type": "string"
          },
          "tracker_approvals": {
            "type": "string",
            "enum": [
              "strict",
              "lenient"
            ]
          },
          "tracker_assignee_only": {
            "type": "boolean",
            "description": "In Jira only the change approval assignee decides it (default false)."
          },
          "tracker_decisions_only": {
            "type": "boolean",
            "description": "Change approvals in Jira are decided in Jira only: approving, rejecting and withdrawing a rejection in Merge Pilot are refused (default false: either). The built-in tracker is not affected."
          },
          "emergency": {
            "$ref": "#/components/schemas/EmergencyRules"
          },
          "no_approver": {
            "type": "string",
            "enum": [
              "manual",
              "auto"
            ],
            "description": "What happens to a change approval nobody could be assigned: wait for someone to take it (default) or assign it once someone may."
          },
          "assignee_deactivated": {
            "type": "string",
            "enum": [
              "reassign",
              "keep_and_warn"
            ],
            "description": "What happens to the open change approvals of a person deactivated in Merge Pilot: assigned again by their policy's assignment rule (`reassign`, the default; nobody who may take one leaves it to `no_approver`), or left assigned with the problem shown on the merge request (`keep_and_warn`). Company admins get `change_approval_assignee_deactivated` either way."
          },
          "change_approval_due_hours": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2160,
            "description": "How long a normal change's change approval may stay open before it is overdue, in hours (0: no deadline, the default; at most 2160, 90 days; 400 otherwise). When a quarter of the time to the deadline is left (at most a day before it) `change_approval_due_soon` is sent, once it passes `change_approval_overdue`; a change approval reopened or whose approval was revoked gets a new deadline from that moment. Emergency changes keep their policy's `review_hours`. A policy's `controls.approval.due_hours` replaces it."
          },
          "vulnerabilities": {
            "type": "object",
            "description": "The vulnerability inventory (zero values take the defaults).",
            "properties": {
              "analyse_on_merge": {
                "type": "boolean",
                "description": "Bring the inventories up to date after a merge into the default branch that changed a dependency manifest, a file that may refer to container images or an infrastructure file (default true)."
              },
              "advisory_check_hours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 720,
                "description": "Look the dependencies in use up for new advisories this often, without the VCS (default 24; 0 = never)."
              },
              "notify_min_severity": {
                "type": "string",
                "enum": [
                  "critical",
                  "high",
                  "medium",
                  "low",
                  "unknown",
                  "none"
                ],
                "description": "Announce new findings at or above (default high)."
              },
              "exception_max_days": {
                "type": "integer",
                "minimum": 1,
                "maximum": 730,
                "description": "Default 90."
              },
              "retention_days": {
                "type": "integer",
                "minimum": 30,
                "maximum": 3650,
                "description": "Fixed findings, ended exceptions and old analysis details (default 365)."
              },
              "image_inventory": {
                "type": "boolean",
                "description": "Scan the container images the default branches refer to into the inventory (default true). Saved off, the image findings (open and fixed) and what was read of the images are deleted (audit vulnerability_inventory_cleared); turned on again, the next analysis starts a new baseline."
              },
              "iac_inventory": {
                "type": "boolean",
                "description": "Check the default branches' infrastructure files into the infrastructure findings (default true). Saved off, the infrastructure findings (open and fixed) and what was read of the files are deleted (audit vulnerability_inventory_cleared); turned on again, the next analysis starts a new baseline."
              }
            }
          },
          "setup_dismissed": {
            "type": "boolean",
            "description": "An administrator hid the setup checklist."
          },
          "direct_changes": {
            "type": "object",
            "description": "What is done about changes made to watched branches without a merge request (zero values take the defaults).",
            "properties": {
              "receive_pushes": {
                "type": "boolean",
                "description": "GitLab project webhooks deliver pushes to the watched branches (default true)."
              },
              "record": {
                "type": "boolean",
                "description": "Record and report them (default true)."
              },
              "refresh_dependencies": {
                "type": "boolean",
                "description": "Bring the inventories up to date when one changes a dependency manifest, a file that may refer to container images or an infrastructure file (default true)."
              },
              "notify": {
                "type": "boolean",
                "description": "Send the direct_change event (default true)."
              },
              "protection_check": {
                "type": "boolean",
                "description": "Check gated projects' branch protection with the head check (default true)."
              },
              "head_check_hours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 168,
                "description": "Compare watched branch heads this often (default 6; 0 = never)."
              },
              "ignore_list": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Login globs (release bots, mirrors) whose pushes are not recorded as direct changes."
              }
            }
          },
          "delegation": {
            "type": "string",
            "enum": [
              "off",
              "self",
              "admin",
              "both"
            ]
          },
          "personal_api_tokens": {
            "type": "boolean",
            "description": "People may create personal API tokens (default true)."
          },
          "audit_retention_days": {
            "type": "integer",
            "minimum": 30,
            "maximum": 3650,
            "description": "How long the company's audit log entries are kept, in days (absent: 365)."
          },
          "governance": {
            "type": "object",
            "properties": {
              "config_approval": {
                "type": "boolean",
                "description": "Four-eyes review of policies, approver pools and risk settings."
              }
            }
          },
          "monitoring": {
            "type": "object",
            "description": "How repositories are watched (fields not listed here are kept as they are).",
            "properties": {
              "open_mr_sweep_hours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 168,
                "description": "How often each repository's open merge requests are listed on the VCS, to find those Merge Pilot never heard of (a lost webhook), in hours (default 6; 0 = never). They are also listed when a repository is added (watched or put under change management)."
              },
              "backfill_days": {
                "type": "integer",
                "minimum": 0,
                "maximum": 365,
                "description": "When a repository is first watched, its merge requests merged in this many days are imported (default 0: none; only what happens from then on is recorded)."
              },
              "auto_watch_include": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Automatic watching takes only repositories whose path matches one of these glob patterns (empty: every one)."
              },
              "auto_watch_exclude": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Repositories whose path matches one of these are never watched automatically."
              },
              "auto_watch_skip_forks": {
                "type": "boolean",
                "description": "Forks are not watched automatically."
              },
              "discovery_max_listed": {
                "type": "integer",
                "minimum": 100,
                "maximum": 100000,
                "description": "Repositories one listing of a connection reads at most (default 20000); a connection reaching more stops automatic watching with an error."
              },
              "discovery_max_per_round": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5000,
                "description": "Repositories one automatic watching round adds at most (default 500); the next round goes on with the rest."
              }
            },
            "additionalProperties": true
          },
          "people": {
            "type": "object",
            "properties": {
              "tracker_match": {
                "type": "string",
                "enum": [
                  "username",
                  "email",
                  "mapping"
                ],
                "description": "How a tracker account is found to be a person: the same user name, the email, or only the tracker account set on them (`mapping`: an email that matches does not count)."
              },
              "change_approval_reporter": {
                "type": "string",
                "enum": [
                  "service_account",
                  "author"
                ]
              }
            }
          },
          "sign_in": {
            "type": "object",
            "description": "Which sign-in methods the company's people may use (`local`, `ldap`, `oidc`, `saml`, `gitlab`, `github`, ...).",
            "additionalProperties": true
          },
          "ldap": {
            "type": "object",
            "description": "Directory settings (`has_bind_password` instead of the password). `tls_mode` is `none`, `ldaps` or `starttls` (`starttls` when left out). When `enabled`, `server`, `base_dn` and a `user_filter` containing `{{username}}` are required (400 otherwise); `ca_certificate` is a PEM certificate trusted besides the system CAs. `email_attribute`, `name_attribute`, `group_attribute` (defaults `mail`, `displayName`, `memberOf`) and `username_attribute` (default: the name typed; e.g. `sAMAccountName`) name the attributes read. `group_filter` (with `{{dn}}` or `{{username}}`) finds groups by a search under `group_base_dn` (default `base_dn`) instead. `roles` (`default_role`, `mappings[]` of `group` and `role`: user, auditor, policy_manager or company_admin) give directory accounts their role from their groups at every sign-in (audit `ldap_role_changed`); their role cannot be changed in Merge Pilot then (400).",
            "additionalProperties": true
          },
          "password_policy": {
            "type": "object",
            "description": "Stricter Merge Pilot passwords and sign-in lockouts for the company's people; looser values than the defaults are refused (400).",
            "properties": {
              "min_length": {
                "type": "integer",
                "minimum": 12,
                "maximum": 72,
                "default": 12
              },
              "max_attempts": {
                "type": "integer",
                "minimum": 3,
                "maximum": 10,
                "default": 10,
                "description": "Failed sign-ins from one address within 15 minutes that lock it out of the account."
              },
              "lockout_minutes": {
                "type": "integer",
                "minimum": 15,
                "maximum": 1440,
                "default": 15
              }
            }
          },
          "smtp": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SMTPConfig"
              }
            ],
            "description": "Mail settings (`has_password` instead of the password); absent without a mail server."
          },
          "default_vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "default_tracker_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "NotificationRoute": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique among the company's routes: a save that repeats an ID is refused with 400 (`route id \"…\" is used by more than one route`). A new route gets one when it is blank. A stored webhook URL or secret is kept only for the saved route with that ID."
          },
          "name": {
            "type": "string"
          },
          "channel_type": {
            "type": "string",
            "enum": [
              "slack",
              "teams",
              "email",
              "webhook"
            ],
            "description": "Checked on create and update: slack, teams and webhook routes need an http(s) webhook_url (webhook routes also a secret); email routes need recipients and the company's mail server."
          },
          "has_webhook_url": {
            "type": "boolean",
            "description": "Read only."
          },
          "has_secret": {
            "type": "boolean",
            "description": "Read only."
          },
          "webhook_url": {
            "type": "string",
            "writeOnly": true,
            "description": "Write only; blank keeps the stored URL."
          },
          "secret": {
            "type": "string",
            "writeOnly": true,
            "description": "Write only (webhook routes): the HMAC key for X-MergePilot-Signature; blank keeps the stored one."
          },
          "recipients": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "E-mail channel: plain addresses (at least one)."
          },
          "path_patterns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "events": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/WebhookEventType"
                },
                {
                  "type": "string",
                  "const": "all"
                }
              ]
            }
          },
          "active": {
            "type": "boolean"
          },
          "stop": {
            "type": "boolean",
            "description": "An event this route takes goes to no route after it. Every active route whose events and path patterns match gets the event, in order; a route that cannot send (an email route while the company has no mail server) is skipped, its stop with it."
          }
        }
      },
      "CompanyUpdate": {
        "type": "object",
        "description": "Every field is optional; only the fields sent change.",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "branch_patterns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "dora_production_branches": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string",
              "maxLength": 255
            },
            "description": "DORA's production branches (see Company); empty: each repository's default branch. A blank entry, a regular expression (\"^main$\", \"(a|b)\") and more than 100 entries are refused."
          },
          "notifications": {
            "type": "object",
            "properties": {
              "routes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NotificationRoute"
                }
              }
            }
          },
          "ldap": {
            "type": "object",
            "additionalProperties": true,
            "description": "May include `bind_password` (write only)."
          },
          "password_policy": {
            "type": "object",
            "description": "Stricter passwords and lockouts (see Company.password_policy); looser than the defaults is refused (400).",
            "properties": {
              "min_length": {
                "type": "integer",
                "minimum": 12,
                "maximum": 72
              },
              "max_attempts": {
                "type": "integer",
                "minimum": 3,
                "maximum": 10
              },
              "lockout_minutes": {
                "type": "integer",
                "minimum": 15,
                "maximum": 1440
              }
            }
          },
          "smtp": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SMTPConfig"
              }
            ],
            "description": "May include `password` (write only). Checked as described in `SMTPConfig` (400 otherwise). A blank password keeps the stored one only for the same host, port, username, tls_mode, auth_mode and CA certificate, and removes it otherwise. An empty `host` removes the mail server (400 while the company has email routes). API tokens cannot change it (403)."
          },
          "scanning": {
            "type": "object",
            "additionalProperties": true
          },
          "registries": {
            "type": "array",
            "description": "Replaces the container registry sign-ins (at most 50; one per host). A blank `secret` keeps the stored one only for the stored registry with that `id` and the same host, kind and user name (400 otherwise: a stored secret is never sent to another registry).",
            "items": {
              "$ref": "#/components/schemas/ContainerRegistry"
            }
          },
          "risk_config": {
            "type": "object",
            "additionalProperties": true,
            "description": "Held for review when four-eyes review is on."
          },
          "approval_fatigue": {
            "type": "object",
            "additionalProperties": true
          },
          "timezone": {
            "type": "string"
          },
          "tracker_approvals": {
            "type": "string",
            "enum": [
              "strict",
              "lenient"
            ]
          },
          "tracker_assignee_only": {
            "type": "boolean",
            "description": "In Jira only the change approval assignee decides it (default false)."
          },
          "tracker_decisions_only": {
            "type": "boolean",
            "description": "Change approvals in Jira are decided in Jira only: approving, rejecting and withdrawing a rejection in Merge Pilot are refused (default false: either). The built-in tracker is not affected."
          },
          "emergency": {
            "$ref": "#/components/schemas/EmergencyRules"
          },
          "no_approver": {
            "type": "string",
            "enum": [
              "manual",
              "auto"
            ],
            "description": "What happens to a change approval nobody could be assigned: wait for someone to take it (default) or assign it once someone may."
          },
          "assignee_deactivated": {
            "type": "string",
            "enum": [
              "reassign",
              "keep_and_warn"
            ],
            "description": "What happens to the open change approvals of a person deactivated in Merge Pilot: assigned again by their policy's assignment rule (`reassign`, the default; nobody who may take one leaves it to `no_approver`), or left assigned with the problem shown on the merge request (`keep_and_warn`). Company admins get `change_approval_assignee_deactivated` either way."
          },
          "change_approval_due_hours": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2160,
            "description": "How long a normal change's change approval may stay open before it is overdue, in hours (0: no deadline, the default; at most 2160, 90 days; 400 otherwise). When a quarter of the time to the deadline is left (at most a day before it) `change_approval_due_soon` is sent, once it passes `change_approval_overdue`; a change approval reopened or whose approval was revoked gets a new deadline from that moment. Emergency changes keep their policy's `review_hours`. A policy's `controls.approval.due_hours` replaces it."
          },
          "vulnerabilities": {
            "type": "object",
            "description": "The vulnerability inventory (zero values take the defaults).",
            "properties": {
              "analyse_on_merge": {
                "type": "boolean",
                "description": "Bring the inventories up to date after a merge into the default branch that changed a dependency manifest, a file that may refer to container images or an infrastructure file (default true)."
              },
              "advisory_check_hours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 720,
                "description": "Look the dependencies in use up for new advisories this often, without the VCS (default 24; 0 = never)."
              },
              "notify_min_severity": {
                "type": "string",
                "enum": [
                  "critical",
                  "high",
                  "medium",
                  "low",
                  "unknown",
                  "none"
                ],
                "description": "Announce new findings at or above (default high)."
              },
              "exception_max_days": {
                "type": "integer",
                "minimum": 1,
                "maximum": 730,
                "description": "Default 90."
              },
              "retention_days": {
                "type": "integer",
                "minimum": 30,
                "maximum": 3650,
                "description": "Fixed findings, ended exceptions and old analysis details (default 365)."
              },
              "image_inventory": {
                "type": "boolean",
                "description": "Scan the container images the default branches refer to into the inventory (default true). Saved off, the image findings (open and fixed) and what was read of the images are deleted (audit vulnerability_inventory_cleared); turned on again, the next analysis starts a new baseline."
              },
              "iac_inventory": {
                "type": "boolean",
                "description": "Check the default branches' infrastructure files into the infrastructure findings (default true). Saved off, the infrastructure findings (open and fixed) and what was read of the files are deleted (audit vulnerability_inventory_cleared); turned on again, the next analysis starts a new baseline."
              }
            }
          },
          "setup_dismissed": {
            "type": "boolean",
            "description": "An administrator hid the setup checklist."
          },
          "direct_changes": {
            "type": "object",
            "description": "What is done about changes made to watched branches without a merge request (zero values take the defaults).",
            "properties": {
              "receive_pushes": {
                "type": "boolean",
                "description": "GitLab project webhooks deliver pushes to the watched branches (default true)."
              },
              "record": {
                "type": "boolean",
                "description": "Record and report them (default true)."
              },
              "refresh_dependencies": {
                "type": "boolean",
                "description": "Bring the inventories up to date when one changes a dependency manifest, a file that may refer to container images or an infrastructure file (default true)."
              },
              "notify": {
                "type": "boolean",
                "description": "Send the direct_change event (default true)."
              },
              "protection_check": {
                "type": "boolean",
                "description": "Check gated projects' branch protection with the head check (default true)."
              },
              "head_check_hours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 168,
                "description": "Compare watched branch heads this often (default 6; 0 = never)."
              },
              "ignore_list": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Login globs (release bots, mirrors) whose pushes are not recorded as direct changes."
              }
            }
          },
          "monitoring": {
            "type": "object",
            "description": "How repositories are watched (fields not listed here are kept as they are).",
            "properties": {
              "open_mr_sweep_hours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 168,
                "description": "How often each repository's open merge requests are listed on the VCS, to find those Merge Pilot never heard of (a lost webhook), in hours (default 6; 0 = never). They are also listed when a repository is added (watched or put under change management)."
              },
              "backfill_days": {
                "type": "integer",
                "minimum": 0,
                "maximum": 365,
                "description": "When a repository is first watched, its merge requests merged in this many days are imported (default 0: none; only what happens from then on is recorded)."
              },
              "auto_watch_include": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Automatic watching takes only repositories whose path matches one of these glob patterns (empty: every one)."
              },
              "auto_watch_exclude": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Repositories whose path matches one of these are never watched automatically."
              },
              "auto_watch_skip_forks": {
                "type": "boolean",
                "description": "Forks are not watched automatically."
              },
              "discovery_max_listed": {
                "type": "integer",
                "minimum": 100,
                "maximum": 100000,
                "description": "Repositories one listing of a connection reads at most (default 20000); a connection reaching more stops automatic watching with an error."
              },
              "discovery_max_per_round": {
                "type": "integer",
                "minimum": 1,
                "maximum": 5000,
                "description": "Repositories one automatic watching round adds at most (default 500); the next round goes on with the rest."
              }
            },
            "additionalProperties": true
          },
          "people": {
            "type": "object",
            "additionalProperties": true
          },
          "sign_in": {
            "type": "object",
            "additionalProperties": true
          },
          "delegation": {
            "type": "string",
            "enum": [
              "off",
              "self",
              "admin",
              "both"
            ]
          },
          "personal_api_tokens": {
            "type": "boolean"
          },
          "audit_retention_days": {
            "type": "integer",
            "minimum": 30,
            "maximum": 3650,
            "description": "How long audit log entries are kept, in days (default 365). API tokens cannot change it (403)."
          },
          "governance": {
            "type": "object",
            "properties": {
              "config_approval": {
                "type": "boolean",
                "description": "Turning review off is itself held for review."
              }
            }
          },
          "default_vcs_connection_id": {
            "type": "string"
          },
          "default_tracker_connection_id": {
            "type": "string"
          }
        }
      },
      "CompanyEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Company"
              }
            }
          }
        ]
      },
      "Connection": {
        "type": "object",
        "description": "A VCS or tracker connection. Tokens, webhook secrets, private keys and client secrets are never returned (`has_*` flags instead).",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "kind": {
            "type": "string",
            "enum": [
              "vcs",
              "tracker"
            ]
          },
          "provider": {
            "type": "string",
            "enum": [
              "gitlab",
              "github",
              "jira",
              "mergepilot"
            ]
          },
          "deployment_type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "token_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the connection's token expires, as GitLab last said (absent: it never does, or it is not known). Company admins get `connection_token_expiring` 14 and 3 days before."
          },
          "health": {
            "type": "object",
            "description": "A problem the connection has (absent: none), shown on the Connections tab; its start and end are announced as `connection_unhealthy` and `connection_recovered` and audited.",
            "properties": {
              "problem": {
                "type": "string",
                "enum": [
                  "token_refused",
                  "app_permissions",
                  "rate_limited",
                  "turned_off"
                ],
                "description": "`token_refused`: the VCS refuses Merge Pilot's credentials (401); `app_permissions`: the GitHub App, or an installation, lacks permissions Merge Pilot asks for; `rate_limited`: the API rate limit leaves background work no calls until it resets; `turned_off`: an admin turned the connection off."
              },
              "since": {
                "type": "string",
                "format": "date-time"
              },
              "until": {
                "type": "string",
                "format": "date-time",
                "description": "`rate_limited` found by a background job: when the VCS said the limit resets (its `Retry-After` or reset time), if it did. The problem is not cleared before then."
              }
            }
          },
          "installation_tokens": {
            "type": "object",
            "description": "GitHub App connections: what the last check of each installation found. A check calls at most 20 installations' tokens a round; the others keep their last result. Suspended and removed installations come from GitHub's list of the App's installations and are not token problems.",
            "properties": {
              "installations": {
                "type": "object",
                "description": "By installation ID.",
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "suspended",
                        "removed",
                        "token_refused",
                        "rate_limited",
                        "unreachable"
                      ],
                      "description": "`ok`: the token worked; `suspended`: GitHub lists the installation as suspended; `removed`: GitHub no longer lists it; `token_refused`: GitHub refused its token; `rate_limited`: its rate limit is used up (`until`); `unreachable`: the check got no answer."
                    },
                    "checked_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "until": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              },
              "checked_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "gitlab_config": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "bot_username": {
                "type": "string",
                "description": "Required for a VCS connection (creating one without it answers 400). The account Merge Pilot approves merge requests with; the only approver of its approval rules."
              },
              "oauth_enabled": {
                "type": "boolean"
              },
              "oauth_client_id": {
                "type": "string"
              },
              "tls_skip_verify": {
                "type": "boolean"
              },
              "has_token": {
                "type": "boolean"
              },
              "has_webhook_secret": {
                "type": "boolean",
                "description": "A webhook secret is required when the connection is created (400 without one): webhooks that do not carry it are ignored."
              },
              "has_oauth_client_secret": {
                "type": "boolean"
              }
            }
          },
          "github_config": {
            "type": "object",
            "description": "GitHub App settings (app id/slug/owner, `app_events` (the events the App subscribes to, as last read from GitHub), `app_permissions`, installations, `has_private_key`, `has_webhook_secret`, `has_client_secret`).",
            "additionalProperties": true,
            "properties": {
              "app_events": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The webhook events the App subscribes to, as last read from GitHub."
              },
              "app_permissions": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "enum": [
                    "read",
                    "write",
                    "admin"
                  ]
                },
                "description": "The App's own permissions (GitHub's permission name to level), as last read from GitHub (`GET /app`) at the last sync."
              },
              "installations": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/GitHubInstallation"
                }
              }
            }
          },
          "jira_config": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "username": {
                "type": "string"
              },
              "auth_method": {
                "type": "string",
                "enum": [
                  "basic",
                  "bearer"
                ],
                "default": "basic",
                "description": "How the token is sent: `basic` (the user name with an API token or password) or `bearer` (a personal access token; Jira Server and Data Center only, 400 on a cloud connection)."
              },
              "tls_skip_verify": {
                "type": "boolean"
              },
              "has_token": {
                "type": "boolean"
              },
              "has_webhook_secret": {
                "type": "boolean",
                "description": "A webhook secret is required when the connection is created (400 without one): webhooks that do not carry it are ignored."
              }
            }
          },
          "mergepilot_config": {
            "type": "object",
            "properties": {
              "tracker_project_id": {
                "$ref": "#/components/schemas/ObjectId"
              }
            }
          },
          "tracker_settings": {
            "$ref": "#/components/schemas/TrackerSettings"
          },
          "vcs_settings": {
            "$ref": "#/components/schemas/VCSSettings"
          },
          "vcs_permissions": {
            "$ref": "#/components/schemas/VCSPermissions"
          },
          "cm_steps": {
            "type": "object",
            "additionalProperties": {
              "type": "boolean"
            },
            "description": "The change management setup steps turned on or off for this connection (see `GET /connections/{id}/cm-steps`)."
          },
          "linked_tracker_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "discovery": {
            "type": "object",
            "description": "The last round of automatic watching of new repositories.",
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "added": {
                "type": "integer",
                "description": "Repositories added in that round."
              },
              "error": {
                "type": "string"
              }
            }
          },
          "last_refused_webhook": {
            "type": "object",
            "description": "The last webhook refused for the connection because it did not\ncarry the connection's webhook secret (recorded at most once a\nminute; each one is also in the audit log as `webhook_refused`).\nEntering a new webhook secret clears it.\n",
            "properties": {
              "reason": {
                "type": "string",
                "enum": [
                  "wrong_secret"
                ]
              },
              "at": {
                "type": "string",
                "format": "date-time"
              },
              "ip": {
                "type": "string",
                "description": "The address the delivery came from."
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "VCSProject": {
        "type": "object",
        "description": "A repository as the VCS describes it.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The repository's ID on the VCS."
          },
          "name": {
            "type": "string"
          },
          "path_with_namespace": {
            "type": "string"
          },
          "web_url": {
            "type": "string"
          },
          "default_branch": {
            "type": "string"
          }
        }
      },
      "VCSGroup": {
        "type": "object",
        "description": "A VCS group (namespace, organization).",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "full_path": {
            "type": "string"
          },
          "web_url": {
            "type": "string"
          }
        }
      },
      "VCSMembership": {
        "type": "object",
        "description": "The caller's membership (groups only `is_member` when not a member).",
        "required": [
          "is_member"
        ],
        "properties": {
          "is_member": {
            "type": "boolean"
          },
          "access_level": {
            "type": "integer",
            "description": "10 Guest, 20 Reporter, 25 Triage, 30 Developer, 40 Maintainer, 50 Owner (with a pending invitation: the role it offers)."
          },
          "username": {
            "type": "string",
            "description": "The caller's VCS username."
          },
          "is_inherited": {
            "type": "boolean",
            "description": "Repositories only (GitLab): the access comes from a parent group."
          },
          "invitation_pending": {
            "type": "boolean",
            "description": "Repositories only (GitHub): an invitation waits to be accepted on GitHub; no access until then."
          },
          "invitation_url": {
            "type": "string",
            "description": "Where to accept it, as GitHub gives it."
          },
          "granted_by_merge_pilot": {
            "type": "boolean",
            "description": "Merge Pilot recorded this access (or invitation) when the caller joined through it (GitLab and GitHub; repositories and groups)."
          },
          "can_leave": {
            "type": "boolean",
            "description": "Repositories only: leaving here is possible (GitHub: access Merge Pilot gave; GitLab: direct membership)."
          }
        }
      },
      "VCSSelfJoin": {
        "type": "object",
        "properties": {
          "access_level": {
            "type": "integer",
            "enum": [
              10,
              20,
              25,
              30
            ],
            "default": 30,
            "description": "The role to join with, one of the VCS's roles up to Developer: GitLab 10 Guest, 20 Reporter, 30 Developer; GitHub 20 Read, 25 Triage, 30 Write (missing or 0: 30; an empty body: 30). Any other level answers 400 naming the allowed roles; a body that is not JSON answers 400 too (it is never read as the default)."
          }
        }
      },
      "VCSVariable": {
        "type": "object",
        "description": "A CI/CD variable or secret.",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string",
            "description": "Never returned for masked or hidden variables nor secrets; otherwise only to callers who may change the variable."
          },
          "value_hidden": {
            "type": "boolean",
            "description": "The variable has a value that is not returned (masked, hidden, or the caller may not change it). Absent when false; secrets have `secret` instead."
          },
          "protected": {
            "type": "boolean"
          },
          "masked": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean",
            "description": "GitLab: masked, and the value is never shown again (chosen when created)."
          },
          "variable_type": {
            "type": "string",
            "enum": [
              "env_var",
              "file"
            ],
            "description": "GitLab only."
          },
          "raw": {
            "type": "boolean",
            "description": "GitLab only: variables in the value are not expanded."
          },
          "description": {
            "type": "string",
            "description": "GitLab only."
          },
          "environment_scope": {
            "type": "string",
            "description": "GitLab: the environment scope (\"*\": all). GitHub: the environment it belongs to (\"\": the repository's own)."
          },
          "secret": {
            "type": "boolean",
            "description": "A write-only value (GitHub secrets)."
          },
          "visibility": {
            "type": "string",
            "enum": [
              "all",
              "private",
              "selected"
            ],
            "description": "GitHub organization values: which repositories see it. Left out elsewhere."
          }
        }
      },
      "VCSGroupVariable": {
        "description": "A group (GitHub organization) variable or secret as listed.",
        "allOf": [
          {
            "$ref": "#/components/schemas/VCSVariable"
          },
          {
            "type": "object",
            "required": [
              "can_change"
            ],
            "properties": {
              "value": {
                "type": "string",
                "description": "Only when `can_change` is true, and never for masked or hidden variables nor secrets."
              },
              "can_change": {
                "type": "boolean",
                "description": "The caller may change (delete) it here: its whole reach is the company's registered repositories, and the `manage_group_vars` rule lets the caller."
              },
              "read_only_reason": {
                "type": "string",
                "description": "Why it is read only, in plain words (e.g. \"every repository in the organization can use it, not only the company's: change it in GitHub\")."
              }
            }
          }
        ]
      },
      "VCSAccessGrant": {
        "type": "object",
        "description": "Repository (GitLab, GitHub) or group (GitLab) access a person got by joining through Merge Pilot.",
        "required": [
          "kind"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "connection_name": {
            "type": "string"
          },
          "provider": {
            "type": "string",
            "enum": [
              "gitlab",
              "github"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "project",
              "group"
            ],
            "description": "What the access is to: a repository (`repo_id`, `repo_path`) or a group (`group_id`, `group_path`)."
          },
          "repo_id": {
            "type": "string",
            "description": "Repositories only."
          },
          "repo_path": {
            "type": "string",
            "description": "Repositories only: the path when the access was given."
          },
          "group_id": {
            "type": "string",
            "description": "Groups only: the GitLab group's ID."
          },
          "group_path": {
            "type": "string",
            "description": "Groups only: the group's full path when the access was given."
          },
          "user_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "username": {
            "type": "string",
            "description": "The Merge Pilot user who joined."
          },
          "vcs_user_id": {
            "type": "string"
          },
          "vcs_username": {
            "type": "string"
          },
          "level": {
            "type": "integer",
            "description": "The level joined with: GitLab 10 Guest, 20 Reporter, 30 Developer; GitHub 20 Read, 25 Triage, 30 Write."
          },
          "role": {
            "type": "string",
            "description": "The VCS role name of `level`."
          },
          "invited": {
            "type": "boolean",
            "description": "GitHub sent an invitation to accept first."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "released_at": {
            "type": "string",
            "format": "date-time",
            "description": "When Merge Pilot stopped tracking it; the access may still exist on the VCS."
          },
          "released_reason": {
            "type": "string",
            "enum": [
              "deactivated",
              "moved_to_another_company",
              "made_platform_admin",
              "connection_deleted",
              "unlinked",
              "project_removed",
              "company_deactivated"
            ],
            "description": "Why Merge Pilot stopped tracking it: the person was deactivated, moved or made platform admin, unlinked their VCS account (access only), the repository was removed from Merge Pilot, the connection deleted or the company deactivated."
          }
        }
      },
      "VCSIssuedToken": {
        "type": "object",
        "description": "A GitLab project access token or deploy token Merge Pilot created for someone. Its value is never stored nor returned here.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "repo_id": {
            "type": "string"
          },
          "repo_path": {
            "type": "string",
            "description": "The repository's path when the token was created."
          },
          "kind": {
            "type": "string",
            "enum": [
              "access",
              "deploy"
            ]
          },
          "vcs_token_id": {
            "type": "string",
            "description": "The token's ID on GitLab."
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "username": {
            "type": "string",
            "description": "A deploy token's user name."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "access_level": {
            "type": "integer",
            "description": "An access token's role: 10 Guest, 20 Reporter, 30 Developer. Absent for deploy tokens."
          },
          "access_role": {
            "type": "string",
            "description": "The VCS role name of `access_level`."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "The expiry date (UTC midnight)."
          },
          "requested_by": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "requested_by_name": {
            "type": "string",
            "description": "The Merge Pilot user who asked for it."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "revoked_at": {
            "type": "string",
            "format": "date-time"
          },
          "revoked_by": {
            "type": "string",
            "description": "Who revoked it through Merge Pilot (user name)."
          },
          "released_at": {
            "type": "string",
            "format": "date-time",
            "description": "When Merge Pilot stopped tracking it (its requester left the company, the repository was removed from Merge Pilot, the connection was deleted or the company deactivated); the token may still work on GitLab."
          },
          "released_reason": {
            "type": "string",
            "enum": [
              "deactivated",
              "moved_to_another_company",
              "made_platform_admin",
              "connection_deleted",
              "unlinked",
              "project_removed",
              "company_deactivated"
            ],
            "description": "Why Merge Pilot stopped tracking it: the person was deactivated, moved or made platform admin, unlinked their VCS account (access only), the repository was removed from Merge Pilot, the connection deleted or the company deactivated."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "expired",
              "revoked",
              "inactive"
            ],
            "description": "`inactive`: GitLab lists it as not active, or no longer has it."
          },
          "can_revoke": {
            "type": "boolean",
            "description": "The caller may revoke it."
          },
          "connection_name": {
            "type": "string",
            "description": "Released tokens only."
          },
          "provider": {
            "type": "string",
            "description": "Released tokens only."
          },
          "connection_deleted": {
            "type": "boolean",
            "description": "Released tokens only: the connection was deleted, so the token cannot be revoked through Merge Pilot."
          }
        }
      },
      "VCSCreatedToken": {
        "type": "object",
        "required": [
          "token",
          "value"
        ],
        "properties": {
          "token": {
            "$ref": "#/components/schemas/VCSIssuedToken"
          },
          "value": {
            "type": "string",
            "description": "The token's value: given in this answer only, never stored by Merge Pilot nor shown again by GitLab."
          }
        }
      },
      "VCSVariableInput": {
        "type": "object",
        "required": [
          "key",
          "value"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          },
          "protected": {
            "type": "boolean",
            "description": "GitLab only."
          },
          "masked": {
            "type": "boolean",
            "description": "GitLab only."
          },
          "environment_scope": {
            "type": "string",
            "description": "GitHub: an existing environment of the repository (not on organizations). GitLab: the environment scope (default `*`; on groups, Premium and Ultimate only)."
          },
          "secret": {
            "type": "boolean",
            "description": "GitHub: create a write-only secret."
          },
          "variable_type": {
            "type": "string",
            "enum": [
              "env_var",
              "file"
            ],
            "description": "GitLab only (default env_var)."
          },
          "raw": {
            "type": "boolean",
            "description": "GitLab only: do not expand variables in the value (left out: GitLab's default, true)."
          },
          "description": {
            "type": "string",
            "description": "GitLab only."
          },
          "hidden": {
            "type": "boolean",
            "description": "GitLab only (17.4+): masked, and the value is never shown again. Only when creating; the value must meet GitLab's masking rules."
          }
        }
      },
      "VCSVariableUpdate": {
        "type": "object",
        "required": [
          "value"
        ],
        "description": "A change to a variable or secret. Options left out are kept.",
        "properties": {
          "value": {
            "type": "string",
            "description": "The new value (always: a hidden or secret value cannot be read back)."
          },
          "protected": {
            "type": "boolean",
            "description": "GitLab only."
          },
          "masked": {
            "type": "boolean",
            "description": "GitLab only. A hidden variable stays masked."
          },
          "variable_type": {
            "type": "string",
            "enum": [
              "env_var",
              "file"
            ],
            "description": "GitLab only."
          },
          "raw": {
            "type": "boolean",
            "description": "GitLab only."
          },
          "description": {
            "type": "string",
            "description": "GitLab only."
          }
        }
      },
      "VCSBranch": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "protected": {
            "type": "boolean"
          },
          "web_url": {
            "type": "string"
          },
          "cm_gated": {
            "type": "boolean",
            "description": "The branch is under change management: only company admins may change its protection. Absent when false."
          }
        }
      },
      "VCSProtectedBranch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "allow_force_push": {
            "type": "boolean"
          },
          "changed_on_vcs": {
            "type": "boolean",
            "description": "GitHub: the ruleset has Merge Pilot's name but was changed on GitHub; Merge Pilot does not change or delete it. Absent when false."
          },
          "changed_reason": {
            "type": "string",
            "description": "How it was changed, e.g. \"its rules were changed\". Absent when not changed."
          },
          "cm_gated": {
            "type": "boolean",
            "description": "The branch (or GitLab wildcard pattern) is under change management: only company admins may unprotect it or change force pushes. Absent when false."
          }
        }
      },
      "TrackerState": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "todo",
              "in_progress",
              "done"
            ]
          },
          "order": {
            "type": "integer"
          },
          "color": {
            "type": "string"
          }
        }
      },
      "TrackerCustomField": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "select",
              "number",
              "date",
              "user",
              "user_multi",
              "boolean"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "required_at_states": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "immutable": {
            "type": "boolean"
          },
          "settable_at_states": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "order": {
            "type": "integer"
          }
        }
      },
      "TrackerProject": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "vcs",
              "manual"
            ]
          },
          "issue_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "states": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrackerState"
            }
          },
          "closing_states": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rejection_states": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "allowed_transitions": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "default_issue_type": {
            "type": "string"
          },
          "custom_fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrackerCustomField"
            }
          },
          "archived": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TrackerIssueUser": {
        "type": "object",
        "properties": {
          "user_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "username": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          }
        }
      },
      "TrackerIssue": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "project_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "tracker_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "key": {
            "type": "string"
          },
          "issue_type": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "assignee": {
            "$ref": "#/components/schemas/TrackerIssueUser"
          },
          "reporter": {
            "$ref": "#/components/schemas/TrackerIssueUser"
          },
          "mr_source": {
            "type": "object",
            "description": "The merge request a change approval was created for.",
            "properties": {
              "vcs_connection_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "repo_id": {
                "type": "string"
              },
              "mr_number": {
                "type": "string"
              },
              "mr_url": {
                "type": "string"
              },
              "commit_sha": {
                "type": "string"
              },
              "mr_author_vcs_username": {
                "type": "string"
              },
              "mr_author_user_id": {
                "$ref": "#/components/schemas/ObjectId"
              }
            }
          },
          "may_decide": {
            "type": "boolean",
            "description": "Change approvals, when read one at a time: whether the caller may decide it, and so change its review attestations."
          },
          "decide_reason": {
            "type": "string",
            "description": "Why the caller may not decide it (with `may_decide` false)."
          },
          "custom_fields": {
            "type": "object",
            "additionalProperties": true
          },
          "state_history": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "state": {
                  "type": "string"
                },
                "entered_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "exited_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "version": {
            "type": "integer",
            "format": "int64",
            "description": "Optimistic-concurrency version; send it back on updates."
          },
          "archived": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_by": {
            "type": "string"
          }
        }
      },
      "TrackerComment": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "issue_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "author": {
            "$ref": "#/components/schemas/TrackerIssueUser"
          },
          "body": {
            "type": "string"
          },
          "system": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TrackerProjectEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TrackerProject"
              }
            }
          }
        ]
      },
      "TrackerIssueEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TrackerIssue"
              }
            }
          }
        ]
      },
      "AuditLog": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "user_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "username": {
            "type": "string",
            "description": "Service tokens appear as `token:<name>`."
          },
          "action": {
            "type": "string"
          },
          "resource": {
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "details": {
            "description": "Action-specific details."
          },
          "status": {
            "type": "string"
          },
          "ip": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookLog": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "vcs_connection_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "source": {
            "type": "string",
            "enum": [
              "vcs",
              "tracker"
            ]
          },
          "event_type": {
            "type": "string"
          },
          "repo_id": {
            "type": "string"
          },
          "mr_number": {
            "type": "string"
          },
          "payload": {
            "description": "The received payload."
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "status_code": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MRWorkflowScan": {
        "type": "object",
        "description": "The CI configuration check of the merge request's head: the changed GitHub Actions workflows, or the changed GitLab CI configuration.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ]
          },
          "head_sha": {
            "type": "string",
            "description": "The commit that was checked."
          },
          "files_scanned": {
            "type": "integer",
            "description": "How many CI configuration files were checked."
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkflowFinding"
            }
          },
          "note": {
            "type": "string",
            "description": "What was not checked and why: a GitLab project whose CI configuration file is outside the repository (an address, or a file in another project) is not checked."
          },
          "error": {
            "type": "string",
            "description": "Why the check could not be completed (status failed)."
          },
          "scanned_at": {
            "type": "string",
            "format": "date-time"
          },
          "queued_at": {
            "type": "string",
            "format": "date-time"
          },
          "failed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the check of head_sha failed."
          }
        }
      },
      "WorkflowFinding": {
        "type": "object",
        "description": "One problem in a CI configuration file. GitHub rules: script-injection (high), untrusted-checkout (high), unpinned-action (medium), write-all (medium), syntax (low). GitLab rules: script-injection (high), debug-trace (high), include-remote (high), include-project-unpinned (medium), component-unpinned (medium), image-unpinned (medium), cache-unprotect (medium), variable-chooses-source (medium), syntax (low).",
        "properties": {
          "file": {
            "type": "string"
          },
          "line": {
            "type": "integer",
            "description": "1-based; absent when the problem has no line (syntax)."
          },
          "rule": {
            "type": "string",
            "enum": [
              "syntax",
              "script-injection",
              "untrusted-checkout",
              "unpinned-action",
              "write-all",
              "include-remote",
              "include-project-unpinned",
              "component-unpinned",
              "image-unpinned",
              "debug-trace",
              "cache-unprotect",
              "variable-chooses-source"
            ]
          },
          "severity": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "MRSourceScan": {
        "type": "object",
        "description": "The dependency source check of the merge request's head (part of the dependency scan).",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "clean",
              "findings",
              "failed"
            ],
            "description": "clean: nothing that fails the check (source-unknown-form findings may be listed); findings; failed: a dependency file could not be read or parsed, or the VCS listed only part of the changed files."
          },
          "count": {
            "type": "integer",
            "description": "The findings that fail the check."
          },
          "informational": {
            "type": "integer",
            "description": "source-unknown-form findings: listed for review, they never fail the check."
          },
          "by_rule": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "The findings that fail the check",
            "per rule.": null
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceFinding"
            },
            "description": "The first 100 findings, failing ones first; the full list is the scan result's source_findings."
          },
          "files_checked": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The dependency files read."
          },
          "error": {
            "type": "string",
            "description": "Why the check could not be completed (status failed)."
          },
          "final": {
            "type": "boolean",
            "description": "Failed only because of what a retry would not change (a cut-short file list, the file limit, under coverage `fail`): not retried."
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "What the check left out where the coverage settings (`incomplete`, `over_limit`: `note`) let it pass anyway; also said in the control's reason."
          }
        }
      },
      "SourceFinding": {
        "type": "object",
        "description": "One dependency source problem. host and url never carry credentials or a query string.",
        "properties": {
          "file": {
            "type": "string"
          },
          "line": {
            "type": "integer"
          },
          "package": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "ecosystem": {
            "type": "string",
            "description": "npm, PyPI, crates.io, RubyGems, Packagist or Go."
          },
          "rule": {
            "type": "string",
            "enum": [
              "lockfile-missing-update",
              "registry-not-allowed",
              "source-git",
              "source-url",
              "source-path",
              "extra-index-url",
              "index-url-not-allowed",
              "find-links",
              "trusted-host",
              "source-unknown-form"
            ]
          },
          "host": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SourceSettings": {
        "type": "object",
        "description": "Where the dependencies a change adds may be fetched from (company defaults of the dependency sources control).",
        "properties": {
          "registries": {
            "type": "object",
            "description": "The company's registries per ecosystem (keys npm, PyPI, crates.io, RubyGems, Packagist), each entry host, host:port or host/path (a scheme and trailing slash are dropped; no credentials, query or wildcards). They are allowed besides the public registries, or instead of them with replace_defaults.",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "replace_defaults": {
            "type": "boolean",
            "default": false,
            "description": "Only the listed registries are allowed, in every ecosystem: the public ones are not."
          },
          "allow_git": {
            "type": "boolean",
            "default": false,
            "description": "A dependency taken from a git repository is not a finding."
          },
          "allow_url": {
            "type": "boolean",
            "default": false,
            "description": "A dependency downloaded from an archive URL is not a finding."
          },
          "allow_path": {
            "type": "boolean",
            "default": false,
            "description": "A dependency taken from a local path or link is not a finding."
          },
          "allowed_packages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Package names (\"*\" wildcards, case-insensitive) whose sources are not checked."
          }
        }
      },
      "SourceOverrides": {
        "type": "object",
        "description": "A policy's own dependency source settings. A field absent or null keeps the company's; registries, when present, replaces the company's registries as a whole, and allowed_packages (also empty) replaces its list.",
        "properties": {
          "registries": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "replace_defaults": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "allow_git": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "allow_url": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "allow_path": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "allowed_packages": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          }
        }
      },
      "AttentionReason": {
        "type": "string",
        "description": "Why an author has to act on their merge request; `primary_reason` is the worst, in this order. `sources_blocked`: the enforced dependency sources control failed; `workflows_blocked`: the enforced CI configuration check failed; `images_blocked` and `iac_blocked`: the enforced container image scan or infrastructure check failed.",
        "enum": [
          "secrets_found",
          "sca_blocked",
          "licenses_blocked",
          "package_health_blocked",
          "sources_blocked",
          "images_blocked",
          "iac_blocked",
          "workflows_blocked",
          "signatures_blocked",
          "ci_failed",
          "code_review_blocked",
          "work_items_blocked",
          "risk_blocked",
          "freeze_held",
          "change_approval_rejected"
        ]
      },
      "DORAMetrics": {
        "type": "object",
        "properties": {
          "deployment_frequency": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "daily_average": {
                "type": "number"
              },
              "trend": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "by_project": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "performance": {
                "type": "string",
                "enum": [
                  "elite",
                  "high",
                  "medium",
                  "low"
                ]
              }
            }
          },
          "lead_time": {
            "type": "object",
            "properties": {
              "p50": {
                "type": "integer"
              },
              "p75": {
                "type": "integer"
              },
              "p90": {
                "type": "integer"
              },
              "trend": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "by_project": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "performance": {
                "type": "string",
                "enum": [
                  "elite",
                  "high",
                  "medium",
                  "low",
                  "no_data"
                ],
                "description": "no_data: nothing to measure in the window."
              }
            }
          },
          "change_failure_rate": {
            "type": "object",
            "additionalProperties": true,
            "description": "rate, total_deploys, failed_deploys, trend, by_project, performance (elite, high, medium, low or no_data: nothing to measure in the window)."
          },
          "mttr": {
            "type": "object",
            "additionalProperties": true,
            "description": "p50, p75, p90, incidents, unrecovered_failures, insufficient_sample, trend, performance (elite, high, medium, low or no_data: no recovered failure in the window)."
          },
          "change_rejection_rate": {
            "type": "object",
            "description": "The change approvals decided in the window (approved or rejected) and the share rejected.",
            "properties": {
              "rate": {
                "type": "number",
                "description": "Percent."
              },
              "decided": {
                "type": "integer"
              },
              "rejected": {
                "type": "integer"
              }
            }
          },
          "risk_correlation": {
            "type": "object",
            "additionalProperties": true
          },
          "window": {
            "type": "string"
          },
          "branches": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The production branches: those named, or the repositories' default branches."
          },
          "default_branches": {
            "type": "boolean",
            "description": "Production includes each repository's default branch (no branches were named, and the company's production branches are unset or include ~DEFAULT_BRANCH)."
          },
          "patterns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The company's production branches beyond the default branches (names and patterns, as set); in branches too."
          },
          "benchmarks": {
            "type": "object",
            "additionalProperties": true
          },
          "definitions": {
            "type": "object",
            "additionalProperties": true
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContainerRegistry": {
        "type": "object",
        "description": "A sign-in to one container registry, for the image scan.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique among the company's registries; a new one gets one when it is blank."
          },
          "name": {
            "type": "string"
          },
          "host": {
            "type": "string",
            "description": "host or host:port, no path: registry.acme.io, ghcr.io, 123456789012.dkr.ecr.eu-west-1.amazonaws.com, europe-docker.pkg.dev, docker.io (Docker Hub under any of its names)."
          },
          "kind": {
            "type": "string",
            "enum": [
              "basic",
              "aws_ecr",
              "gcp"
            ],
            "description": "`basic`: a user name and a password or token; `aws_ecr`: an access key ID (`username`) and secret access key (`secret`), turned into an ECR token; `gcp`: a service account key (`secret`, JSON), turned into an access token."
          },
          "username": {
            "type": "string"
          },
          "secret": {
            "type": "string",
            "writeOnly": true,
            "description": "Write only; blank keeps the stored one (see CompanyUpdate.registries)."
          },
          "has_secret": {
            "type": "boolean",
            "description": "Read only."
          },
          "region": {
            "type": "string",
            "description": "`aws_ecr`: the region (empty: taken from the host)."
          },
          "ca_certificate": {
            "type": "string",
            "description": "PEM certificate trusted besides the system CAs."
          },
          "tls_skip_verify": {
            "type": "boolean"
          }
        }
      },
      "ImageScanSettings": {
        "type": "object",
        "description": "The container image scan (zero values take the defaults).",
        "properties": {
          "block_unfixed": {
            "type": "boolean",
            "description": "Vulnerabilities without a fixed version also hold the gate (default false: they are listed, never hidden)."
          },
          "unresolved": {
            "type": "string",
            "enum": [
              "fail",
              "note"
            ],
            "description": "A reference that depends on a variable or template: fails the scan (default) or is listed."
          },
          "unknown_severity": {
            "type": "string",
            "enum": [
              "show",
              "high",
              "block"
            ],
            "description": "A vulnerability the scanner gives no rating: listed, never held (default), counted as high, or always held."
          },
          "skipped_images": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Image names (\"*\" wildcards) not scanned."
          },
          "platform": {
            "type": "string",
            "description": "os/arch[/variant] of multi-platform images (default linux/amd64)."
          },
          "max_images": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "New images one change may refer to before the scan fails (0: 20)."
          },
          "internal_hosts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Hosts on private networks the image and infrastructure scans may reach besides the registries (an internal Terraform module registry, a registry's token service on another host). The scans reach public addresses, the registries' hosts and these, never cloud metadata or loopback addresses. Company only."
          }
        }
      },
      "IaCScanSettings": {
        "type": "object",
        "description": "The infrastructure check (zero values take the defaults).",
        "properties": {
          "types": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "enum": [
                "terraform",
                "kubernetes",
                "helm",
                "dockerfile",
                "cloudformation",
                "azure-arm"
              ]
            },
            "description": "Checked types (absent or null: all; []: none)."
          },
          "skipped_checks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Check IDs not reported (`KSV-0017`, \"*\" wildcards)."
          },
          "skipped_paths": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "File patterns not checked."
          },
          "max_files": {
            "type": "integer",
            "minimum": 0,
            "maximum": 500,
            "description": "Infrastructure files one change may touch before the check fails (0: 50)."
          },
          "unchecked": {
            "type": "string",
            "enum": [
              "fail",
              "note"
            ],
            "description": "A changed file that cannot be checked: fails the check (default) or is listed."
          }
        }
      },
      "ScannedImage": {
        "type": "object",
        "properties": {
          "image": {
            "type": "string",
            "description": "Normalized: registry/repository[:tag][@digest]."
          },
          "digest": {
            "type": "string"
          },
          "os": {
            "type": "string"
          },
          "refs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "\"file:line\" places referring to it."
          },
          "fixable": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Vulnerabilities with a fixed version by severity (critical, high, medium, low, unknown); one exploited in the wild counts as critical when `scanning.sca.kev` is critical."
          },
          "unfixed": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Vulnerabilities without a fixed version by severity."
          },
          "kev": {
            "type": "integer",
            "description": "Vulnerabilities exploited in the wild (CISA KEV)."
          },
          "error": {
            "type": "string",
            "description": "Why the image could not be scanned (the scan then failed)."
          }
        }
      },
      "MRImageScan": {
        "type": "object",
        "description": "The container image scan of the images the merge request starts referring to (`pending`, `completed` or `failed`). The vulnerabilities are in the result (`result_id`).",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ]
          },
          "head_sha": {
            "type": "string"
          },
          "images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScannedImage"
            }
          },
          "unresolved": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "ref": {
                  "type": "string",
                  "description": "\"file:line\"."
                },
                "raw": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          },
          "result_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "error": {
            "type": "string"
          },
          "scanned_at": {
            "type": "string",
            "format": "date-time"
          },
          "queued_at": {
            "type": "string",
            "format": "date-time"
          },
          "failed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ImageScanResult": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "mr_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "head_sha": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "image": {
                  "type": "string"
                },
                "digest": {
                  "type": "string"
                },
                "os": {
                  "type": "string"
                },
                "vulns": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "CVE or other advisory ID."
                      },
                      "package": {
                        "type": "string"
                      },
                      "installed": {
                        "type": "string"
                      },
                      "fixed": {
                        "type": "string",
                        "description": "The first fixed version (empty when none)."
                      },
                      "status": {
                        "type": "string",
                        "description": "The vendor's: fixed, affected, fix_deferred, will_not_fix, ..."
                      },
                      "severity": {
                        "type": "string",
                        "enum": [
                          "critical",
                          "high",
                          "medium",
                          "low",
                          "unknown"
                        ]
                      },
                      "title": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string"
                      },
                      "target": {
                        "type": "string",
                        "description": "Where the package is (the OS, a language's packages)."
                      },
                      "type": {
                        "type": "string",
                        "description": "The package type (alpine, debian, python-pkg, jar, ...)."
                      },
                      "kev": {
                        "type": "boolean"
                      },
                      "epss": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "IaCFinding": {
        "type": "object",
        "properties": {
          "file": {
            "type": "string"
          },
          "line": {
            "type": "integer"
          },
          "end_line": {
            "type": "integer"
          },
          "check": {
            "type": "string",
            "description": "KSV-0017, DS-0002, AWS-0107, ..."
          },
          "type": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "critical",
              "high",
              "medium",
              "low",
              "unknown"
            ]
          },
          "title": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "resolution": {
            "type": "string"
          },
          "resource": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "The check's description."
          }
        }
      },
      "MRIaCScan": {
        "type": "object",
        "description": "The infrastructure check of the files the merge request touches: the misconfigurations it introduces (`pending`, `completed` or `failed`).",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ]
          },
          "head_sha": {
            "type": "string"
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IaCFinding"
            }
          },
          "files_scanned": {
            "type": "integer"
          },
          "existing": {
            "type": "integer",
            "description": "Findings the target branch already has in these files (not reported)."
          },
          "unchecked": {
            "type": "array",
            "description": "Changed files (a chart: its directory) that could not be checked, or were checked without something they refer to (`partial`: a Terraform module that could not be downloaded).",
            "items": {
              "type": "object",
              "properties": {
                "file": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "partial": {
                  "type": "boolean"
                }
              }
            }
          },
          "error": {
            "type": "string"
          },
          "scanned_at": {
            "type": "string",
            "format": "date-time"
          },
          "queued_at": {
            "type": "string",
            "format": "date-time"
          },
          "failed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "IaCFindingRecord": {
        "type": "object",
        "description": "A misconfiguration on a project's default branch, followed from first seen until fixed.",
        "allOf": [
          {
            "$ref": "#/components/schemas/IaCFinding"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "company_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "project_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "project_path": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "open",
                  "fixed"
                ]
              },
              "source": {
                "type": "string",
                "enum": [
                  "analysis",
                  "merge",
                  "direct"
                ]
              },
              "first_seen_at": {
                "type": "string",
                "format": "date-time"
              },
              "last_seen_at": {
                "type": "string",
                "format": "date-time"
              },
              "fixed_at": {
                "type": "string",
                "format": "date-time"
              },
              "introduced_by": {
                "type": "object",
                "additionalProperties": true,
                "description": "The merge request that brought it ({id, number, title, merged_at})."
              },
              "fixed_by": {
                "type": "object",
                "additionalProperties": true
              },
              "baseline": {
                "type": "boolean",
                "description": "Already there at the project's first infrastructure check."
              }
            }
          }
        ]
      },
      "Delegation": {
        "type": "object",
        "description": "`delegate_id` votes in `user_id`'s place from `from` until `until`.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "user_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "delegate_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "until": {
            "type": "string",
            "format": "date-time"
          },
          "reason": {
            "type": "string"
          },
          "created_by": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "user_name": {
            "type": "string"
          },
          "delegate_name": {
            "type": "string"
          }
        }
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "job_id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "claimed",
              "processing",
              "completed",
              "failed",
              "retry"
            ]
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "priority": {
            "type": "integer"
          },
          "payload": {
            "type": "object",
            "additionalProperties": true
          },
          "result": {
            "type": "object",
            "properties": {
              "policy": {
                "type": "string"
              },
              "gate": {
                "type": "string",
                "enum": [
                  "approved",
                  "pending",
                  "blocked"
                ]
              },
              "watched": {
                "type": "boolean",
                "description": "Only recorded (a watched repository): nothing was held."
              },
              "change_approval_key": {
                "type": "string"
              },
              "head_sha": {
                "type": "string",
                "description": "The merge request head commit an mr_process or mr_evaluate job read."
              },
              "actions_taken": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "retry_info": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "WebhookEventType": {
        "type": "string",
        "description": "The events a notification route can take (`all` in a route's `events` takes every one, including events added later).",
        "enum": [
          "mr_processed",
          "mr_merged",
          "mr_merged_without_approval",
          "mr_merged_in_freeze",
          "mr_sod_violation",
          "mr_approval_revoked_after_merge",
          "mr_rejected",
          "mr_approvers_short",
          "change_approval_created",
          "change_approval_closed",
          "change_approval_rejected",
          "change_approval_reassigned",
          "secrets_detected",
          "vulnerabilities_detected",
          "vulnerability_found",
          "direct_change",
          "protection_weakened",
          "mr_risk_assessed",
          "approval_fatigue",
          "emergency_declared",
          "emergency_review_overdue",
          "job_failed",
          "mr_blocked",
          "change_approval_due_soon",
          "change_approval_overdue",
          "connection_unhealthy",
          "connection_recovered",
          "malicious_package_detected",
          "license_denied",
          "dependency_sources_detected",
          "ci_config_problems",
          "image_vulnerabilities_detected",
          "iac_problems_detected",
          "sso_check_failed",
          "ldap_check_failed",
          "license_expiring",
          "user_role_changed",
          "access_released",
          "branch_unprotected_by_admin",
          "notification_failed",
          "change_approval_assignee_deactivated",
          "api_token_expiring",
          "service_token_expiring",
          "connection_token_expiring"
        ]
      },
      "WebhookEvent": {
        "type": "object",
        "description": "Body of an outbound webhook (`application/json`). Verify the\nsignature over the raw bytes before parsing.\n",
        "required": [
          "event",
          "company_id",
          "occurred_at",
          "data"
        ],
        "properties": {
          "event": {
            "$ref": "#/components/schemas/WebhookEventType"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "UTC."
          },
          "data": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "company": {
                "type": "string",
                "description": "Company slug."
              },
              "repo_id": {
                "type": "string"
              },
              "mr_number": {
                "type": "string"
              },
              "project": {
                "type": "string",
                "description": "Project path (empty when unknown)."
              },
              "vcs_connection_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "url": {
                "type": "string",
                "format": "uri",
                "description": "The page in Merge Pilot the event is about. Left out when the platform has no address set."
              },
              "mr_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "project_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "change_approval_key": {
                "type": "string"
              },
              "actor": {
                "type": "string",
                "description": "Who did it: merged, pushed, approved, declared, took over, changed the role or removed the protection."
              },
              "branch": {
                "type": "string",
                "description": "direct_change and branch_unprotected_by_admin: the branch."
              },
              "severity": {
                "type": "string",
                "description": "Risk level or the worst vulnerability severity."
              },
              "policy": {
                "type": "string"
              },
              "counts": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Event counts, e.g. findings, vulnerabilities and critical, commits, changes (a direct_change digest), eligible and required, failed_controls, malicious, denied, projects, problems, grants and tokens, days."
              },
              "job_id": {
                "type": "string"
              },
              "job_type": {
                "type": "string"
              },
              "error_category": {
                "type": "string",
                "description": "job_failed and notification_failed: the kind of failure. The error itself is only in the audit log."
              },
              "connection_id": {
                "$ref": "#/components/schemas/ObjectId"
              },
              "problem": {
                "type": "string",
                "enum": [
                  "token_refused",
                  "app_permissions",
                  "rate_limited",
                  "turned_off"
                ],
                "description": "connection_unhealthy: the problem; connection_recovered: the problem that is gone."
              },
              "due_at": {
                "type": "string",
                "format": "date-time",
                "description": "change_approval_due_soon and change_approval_overdue: the deadline; license_expiring: when the license expires."
              },
              "user": {
                "type": "string",
                "description": "user_role_changed: whose role changed."
              },
              "reason": {
                "type": "string",
                "description": "access_released: why (deactivated, moved_to_another_company, made_platform_admin, connection_deleted, unlinked, project_removed, company_deactivated)."
              },
              "route": {
                "type": "string",
                "description": "notification_failed: the route whose delivery failed; a route test: the route tested."
              },
              "event": {
                "type": "string",
                "description": "notification_failed: the event type that was not delivered."
              }
            }
          }
        },
        "examples": [
          {
            "event": "change_approval_created",
            "company_id": "65f1c2a9e4b0a1b2c3d4e5f6",
            "occurred_at": "2026-10-23T09:12:44.123456Z",
            "data": {
              "title": "Change approval created",
              "message": "Change approval CMG-17 was created for MR !42 (group/service)",
              "company": "acme",
              "repo_id": "1234",
              "mr_number": "42",
              "project": "group/service",
              "vcs_connection_id": "65f1c2a9e4b0a1b2c3d4e5f7",
              "url": "https://mergepilot.example.com/merge-requests/65f1c2a9e4b0a1b2c3d4e5f8",
              "mr_id": "65f1c2a9e4b0a1b2c3d4e5f8",
              "change_approval_key": "CMG-17"
            }
          }
        ]
      },
      "NotificationDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "route_id": {
            "type": "string",
            "description": "Empty for a personal email."
          },
          "channel": {
            "type": "string",
            "enum": [
              "slack",
              "teams",
              "email",
              "webhook",
              "person"
            ],
            "description": "The route's channel when the event was queued; `person` for a personal email."
          },
          "user_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "username": {
            "type": "string",
            "description": "Personal email: its person."
          },
          "to": {
            "type": "string",
            "description": "Personal email: the address it was queued for (it is sent to the person's address at the time)."
          },
          "event": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/WebhookEventType"
              },
              {
                "type": "string",
                "const": "test",
                "description": "A route test (Send test)."
              }
            ]
          },
          "body": {
            "type": "string",
            "description": "Webhook routes: the exact JSON sent (and signed)."
          },
          "notice": {
            "type": "object",
            "description": "Slack, Teams and email routes. The message sent.",
            "properties": {
              "title": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "color": {
                "type": "string",
                "enum": [
                  "good",
                  "warning",
                  "danger"
                ]
              },
              "company_name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "description": "The page in Merge Pilot the event is about; absent when the app's address is not set."
              },
              "reason": {
                "type": "string",
                "description": "The footer's \"You get this because …\"."
              },
              "settings_url": {
                "type": "string",
                "description": "Where the reader changes it: the company's Notifications tab, or My profile for a personal email."
              },
              "at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "delivered",
              "failed",
              "skipped"
            ],
            "description": "`skipped`: not sent and never to be; the reason is the attempt's `error`. A route's delivery: *the route was turned off* or *the route was removed or moved to another channel* (after it was queued; a route test is sent to a route turned off too). A personal email: *the person no longer exists*, *the person was deactivated or left the company*, *the person has no valid email address*, *the person's role no longer gets these emails*, *the person turned these emails off*, or *the company has no mail server*."
          },
          "attempts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "status_code": {
                  "type": "integer"
                },
                "error": {
                  "type": "string"
                },
                "duration_ms": {
                  "type": "integer"
                }
              }
            }
          },
          "next_attempt_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "delivered_at": {
            "type": "string",
            "format": "date-time"
          },
          "delivered_to": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Email routes: the recipients whose mail server accepted the message."
          },
          "refused_to": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Email routes: the recipients whose mail server refused the message for good (a 5yz reply); they are not sent it again."
          }
        }
      },
      "SMTPConfig": {
        "type": "object",
        "description": "The company's mail server, for email routes and personal emails.\nChecked on save and on test: the port 1-65535 (any port), `tls_mode`\nand `auth_mode` from the lists, authentication only with `starttls`\nor `tls` unless the host is localhost, 127.0.0.1 or ::1, a user name\nwith authentication, a plain from address, a from name of at most 100\ncharacters on one line, and a PEM CA certificate.\n",
        "properties": {
          "host": {
            "type": "string",
            "description": "Host name or IP address; empty removes the mail server."
          },
          "port": {
            "type": "integer",
            "minimum": 1,
            "maximum": 65535
          },
          "tls_mode": {
            "type": "string",
            "enum": [
              "starttls",
              "tls",
              "none"
            ],
            "description": "`starttls`: upgraded after connecting (sending fails when the server does not offer it); `tls`: implicit TLS from the start; `none`: no encryption. Certificates must be valid for the host and trusted."
          },
          "auth_mode": {
            "type": "string",
            "enum": [
              "plain",
              "login",
              "cram-md5",
              "none"
            ]
          },
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string",
            "writeOnly": true
          },
          "has_password": {
            "type": "boolean",
            "readOnly": true
          },
          "from_address": {
            "type": "string",
            "format": "email"
          },
          "from_name": {
            "type": "string",
            "maxLength": 100
          },
          "ca_certificate": {
            "type": "string",
            "description": "Optional PEM certificate trusted besides the system CAs, for a mail server whose certificate the company's own CA issued."
          }
        }
      },
      "NotificationPrefsEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "available": {
                    "type": "boolean",
                    "description": "False for a platform admin (no company, no personal emails)."
                  },
                  "mail_server": {
                    "type": "boolean",
                    "description": "The company has a mail server; without one no personal email is sent (choices are kept)."
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "event": {
                          "$ref": "#/components/schemas/WebhookEventType"
                        },
                        "group": {
                          "type": "string",
                          "enum": [
                            "change_approvals",
                            "my_changes",
                            "findings",
                            "administration",
                            "account"
                          ]
                        },
                        "as": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "assignee",
                              "approver",
                              "author",
                              "admin",
                              "self"
                            ]
                          },
                          "description": "Why it can reach this person."
                        },
                        "enabled": {
                          "type": "boolean"
                        },
                        "default": {
                          "type": "boolean",
                          "description": "On before the person chose (every personal event but connection_recovered)."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "UnsubscribeDetailsEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "event": {
                    "$ref": "#/components/schemas/WebhookEventType"
                  },
                  "company": {
                    "type": "string"
                  },
                  "username": {
                    "type": "string"
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "The person gets these emails now."
                  }
                }
              }
            }
          }
        ]
      },
      "MyIdentityProvider": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "oidc",
              "saml"
            ]
          },
          "linked": {
            "type": "boolean"
          },
          "username": {
            "type": "string",
            "description": "Who the account is at the provider, when linked."
          },
          "gives_role": {
            "type": "boolean",
            "description": "The provider sets the account's role (it cannot be unlinked)."
          }
        }
      },
      "SignInMethods": {
        "type": "object",
        "description": "Sign-in methods the platform allows companies to turn on (`true` = allowed). Answers always carry every method.",
        "properties": {
          "local": {
            "type": "boolean",
            "description": "A Merge Pilot password."
          },
          "ldap": {
            "type": "boolean",
            "description": "The company's LDAP directory."
          },
          "oidc": {
            "type": "boolean",
            "description": "An OpenID Connect identity provider of the company."
          },
          "saml": {
            "type": "boolean",
            "description": "A SAML 2.0 identity provider of the company."
          },
          "gitlab": {
            "type": "boolean",
            "description": "A GitLab account (VCS connection)."
          },
          "github": {
            "type": "boolean",
            "description": "A GitHub account (VCS connection)."
          }
        }
      },
      "LicenseState": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "",
              "online",
              "offline"
            ],
            "description": "Empty when no license is set."
          },
          "fingerprint": {
            "type": "string",
            "description": "This instance's fingerprint, bound to the license."
          },
          "valid": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "description": "Why the license is not valid."
          },
          "plan": {
            "type": "string"
          },
          "features": {
            "type": "object",
            "additionalProperties": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "has_api_key": {
            "type": "boolean"
          },
          "has_license_key": {
            "type": "boolean"
          },
          "has_offline_license": {
            "type": "boolean"
          },
          "grace_until": {
            "type": "string",
            "format": "date-time",
            "description": "The license expired, and Merge Pilot keeps working until then (`license_grace_days`)."
          }
        }
      },
      "LicenseStateEnvelope": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/LicenseState"
              }
            }
          }
        ]
      },
      "FlowEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "stage": {
            "type": "string",
            "description": "`webhook_received`, `job_` plus the job type, or `audit_` plus the audit action."
          },
          "status": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "details_kv": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "details_text": {
            "type": "string"
          },
          "duration_ms": {
            "type": "integer"
          },
          "source": {
            "type": "string",
            "description": "Where the event comes from: the webhook source, `job` or `audit`."
          },
          "actor": {
            "type": "string"
          }
        }
      },
      "APICall": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "service": {
            "type": "string",
            "enum": [
              "gitlab",
              "github",
              "jira"
            ]
          },
          "method": {
            "type": "string"
          },
          "endpoint": {
            "type": "string",
            "description": "Path of the called URL."
          },
          "status_code": {
            "type": "integer",
            "description": "0 when no answer was received."
          },
          "latency_ms": {
            "type": "integer"
          },
          "is_success": {
            "type": "boolean"
          },
          "error_msg": {
            "type": "string"
          },
          "response_body": {
            "type": "string",
            "description": "Start of the answer of a failed call."
          },
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "mr_context": {
            "type": "object",
            "description": "The merge request the call was made for.",
            "properties": {
              "project_id": {
                "type": "integer"
              },
              "mr_iid": {
                "type": "integer"
              }
            }
          },
          "called_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ConnectionInput": {
        "type": "object",
        "description": "A new connection. Secrets (`token`, `webhook_secret`, `oauth_client_secret`, `private_key`, `client_secret`) are write-only.",
        "required": [
          "company_id",
          "kind",
          "provider",
          "deployment_type",
          "name"
        ],
        "properties": {
          "company_id": {
            "$ref": "#/components/schemas/ObjectId"
          },
          "kind": {
            "type": "string",
            "enum": [
              "vcs",
              "tracker"
            ]
          },
          "provider": {
            "type": "string",
            "enum": [
              "gitlab",
              "github",
              "jira",
              "mergepilot"
            ]
          },
          "deployment_type": {
            "type": "string",
            "enum": [
              "cloud",
              "on_prem"
            ],
            "description": "The built-in tracker (`mergepilot`) is `cloud` only."
          },
          "name": {
            "type": "string"
          },
          "active": {
            "type": "boolean",
            "default": true
          },
          "gitlab_config": {
            "$ref": "#/components/schemas/GitLabConfigInput"
          },
          "github_config": {
            "$ref": "#/components/schemas/GitHubConfigInput"
          },
          "jira_config": {
            "$ref": "#/components/schemas/JiraConfigInput"
          },
          "mergepilot_config": {
            "$ref": "#/components/schemas/MergePilotConfigInput"
          }
        }
      },
      "GitLabConfigInput": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The GitLab address (http or https; not a loopback or cloud metadata address)."
          },
          "token": {
            "type": "string",
            "writeOnly": true,
            "description": "The access token of the bot account."
          },
          "bot_username": {
            "type": "string",
            "description": "Required for a VCS connection. The account Merge Pilot approves merge requests with."
          },
          "webhook_secret": {
            "type": "string",
            "writeOnly": true,
            "description": "Required when the connection is created."
          },
          "oauth_enabled": {
            "type": "boolean",
            "description": "People may sign in and link their GitLab account through this connection."
          },
          "oauth_client_id": {
            "type": "string"
          },
          "oauth_client_secret": {
            "type": "string",
            "writeOnly": true
          },
          "tls_skip_verify": {
            "type": "boolean",
            "description": "Do not verify the server's TLS certificate (a private certificate authority)."
          }
        }
      },
      "GitHubConfigInput": {
        "type": "object",
        "description": "The App fields are normally filled by the manifest flow; they can be entered by hand for an App registered elsewhere (`app_id` together with `private_key`).",
        "properties": {
          "web_url": {
            "type": "string",
            "description": "`https://github.com` for a cloud connection; the GitHub Enterprise Server address for an on-premises one."
          },
          "app_id": {
            "type": "integer",
            "format": "int64"
          },
          "app_slug": {
            "type": "string"
          },
          "client_id": {
            "type": "string"
          },
          "client_secret": {
            "type": "string",
            "writeOnly": true
          },
          "private_key": {
            "type": "string",
            "writeOnly": true,
            "description": "The App's private key (PEM)."
          },
          "webhook_secret": {
            "type": "string",
            "writeOnly": true
          },
          "oauth_enabled": {
            "type": "boolean",
            "description": "People may sign in and link their GitHub account through the App."
          },
          "tls_skip_verify": {
            "type": "boolean"
          }
        }
      },
      "JiraConfigInput": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "auth_method": {
            "type": "string",
            "enum": [
              "basic",
              "bearer"
            ],
            "default": "basic",
            "description": "`basic` (the user name with an API token or password) or `bearer` (a personal access token; Jira Server and Data Center only)."
          },
          "token": {
            "type": "string",
            "writeOnly": true
          },
          "webhook_secret": {
            "type": "string",
            "writeOnly": true,
            "description": "Required when the connection is created."
          },
          "tls_skip_verify": {
            "type": "boolean"
          }
        }
      },
      "MergePilotConfigInput": {
        "type": "object",
        "description": "The built-in tracker. Required for the `mergepilot` provider.",
        "properties": {
          "tracker_project_id": {
            "$ref": "#/components/schemas/ObjectId",
            "description": "A tracker project of the company in VCS mode, not archived."
          }
        }
      },
      "GitHubInstallation": {
        "type": "object",
        "description": "An account (organization or user) the GitHub App is installed on.",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "account": {
            "type": "string"
          },
          "account_type": {
            "type": "string",
            "enum": [
              "Organization",
              "User"
            ]
          },
          "repository_selection": {
            "type": "string",
            "enum": [
              "all",
              "selected"
            ]
          },
          "suspended_at": {
            "type": "string",
            "format": "date-time"
          },
          "permissions": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "read",
                "write",
                "admin"
              ]
            },
            "description": "The App permissions the installation has accepted, as last read from GitHub."
          },
          "html_url": {
            "type": "string",
            "description": "The installation's settings page on GitHub, as GitHub gives it (where its owner accepts new permissions)."
          },
          "permission_issues": {
            "type": "array",
            "description": "Computed when the connection is read (never stored; not in the sync answer). The permissions Merge Pilot asks for that this installation cannot use yet. Empty or absent when there are none, or while the App's or the installation's permissions have not been read.",
            "items": {
              "$ref": "#/components/schemas/GitHubPermissionIssue"
            }
          }
        }
      },
      "GitHubPermissionIssue": {
        "type": "object",
        "description": "A permission Merge Pilot's App manifest asks for that an installation cannot use. A level counts when it is at least the one asked for (read < write < admin).",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "missing",
              "pending"
            ],
            "description": "`missing`: the App itself lacks it (or has a lower level); its owner adds it in the App's settings. `pending`: the App has it, the installation has not accepted it yet; the account's owner accepts it on the installation's page (`html_url`). GitHub's `installation` event `new_permissions_accepted` re-reads the installations."
          },
          "permission": {
            "type": "string",
            "description": "The manifest key, e.g. `environments`."
          },
          "name": {
            "type": "string",
            "description": "As GitHub's settings page names it, e.g. `Environments`."
          },
          "scope": {
            "type": "string",
            "enum": [
              "repository",
              "organization",
              "account"
            ]
          },
          "required": {
            "type": "string",
            "enum": [
              "read",
              "write",
              "admin"
            ]
          },
          "granted": {
            "type": "string",
            "description": "The level the App (missing) or the installation (pending) has; absent for none."
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The Merge Pilot features that do not work without it."
          }
        }
      },
      "VCSOpRule": {
        "type": "object",
        "description": "Who may ask Merge Pilot for one operation, which Merge Pilot then does with the connection's account. Company admins always may.",
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Off: only company admins."
          },
          "roles": {
            "type": "array",
            "description": "The Merge Pilot roles that may ask for it (none - company admins only).",
            "items": {
              "type": "string",
              "enum": [
                "user",
                "policy_manager"
              ]
            }
          },
          "min_access": {
            "type": "integer",
            "description": "The lowest role the caller's linked VCS account must hold on the repository, read with the connection's account: GitLab 10 Guest, 20 Reporter, 30 Developer, 40 Maintainer, 50 Owner; GitHub 20 Read, 25 Triage, 30 Write, 40 Maintain, 50 Admin. The lowest is \"any access\" (GitLab Minimal access, and the read everyone has on a public GitHub repository, are no access). For group variables it counts on one of the company's registered repositories in the group. 0 for join_projects and join_groups (no minimum), and allowed for a rule that is off."
          }
        }
      },
      "VCSPermissions": {
        "type": "object",
        "description": "The connection's rules for what people other than company admins may ask Merge Pilot to do on the VCS, one per operation (a missing one is off). The UI turns a rule on with roles user and policy_manager and minimum 30 (GitLab Developer, GitHub Write).",
        "properties": {
          "join_projects": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "join_groups": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "cm_setup": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "cm_remove": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "view_variables": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "manage_project_vars": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "manage_group_vars": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "protect_branches": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "unprotect_branches": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "force_push": {
            "$ref": "#/components/schemas/VCSOpRule"
          },
          "create_access_tokens": {
            "$ref": "#/components/schemas/VCSOpRule",
            "description": "GitLab only (turning it on for GitHub is 400): create project access tokens, and revoke tokens created through Merge Pilot."
          },
          "create_deploy_tokens": {
            "$ref": "#/components/schemas/VCSOpRule",
            "description": "GitLab only (turning it on for GitHub is 400): create deploy tokens, and revoke tokens created through Merge Pilot."
          }
        }
      },
      "TrackerSettings": {
        "type": "object",
        "description": "How change approvals are created on a tracker and which statuses decide them.",
        "required": [
          "project_key",
          "issue_type"
        ],
        "properties": {
          "project_key": {
            "type": "string",
            "description": "The tracker project change approvals are created in."
          },
          "issue_type": {
            "type": "string"
          },
          "work_item_projects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The projects work items belong to (keys of other projects are ignored); empty means any of the tracker's projects."
          },
          "work_item_pattern": {
            "type": "string",
            "description": "A regular expression replacing the default work item key pattern (its first group",
            "or the whole match": null,
            "is the key).": null
          },
          "custom_fields": {
            "type": "object",
            "description": "Fields set on a new change approval, by field ID.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string",
                  "description": "The value or template."
                },
                "type": {
                  "type": "string",
                  "description": "The field's type (empty is text)."
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "closing_statuses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Statuses that approve the change (not used by the built-in tracker)."
          },
          "rejection_statuses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Statuses that reject the change (not used by the built-in tracker)."
          },
          "reopen_status": {
            "type": "string",
            "description": "Where a change approval moves back to when a policy reopens it on new commits; empty creates a new change approval instead."
          },
          "merged_status": {
            "type": "string",
            "description": "Where a change approval moves when its merge request is merged, once approved: one still undecided at the merge (an emergency change's review) moves there when its review approves it (optional)."
          },
          "cancelled_status": {
            "type": "string",
            "description": "Where an undecided change approval moves when its merge request is closed without merging (optional)."
          },
          "cancel_approved_superseded": {
            "type": "boolean",
            "description": "Also move a change approval that was approved to the cancelled status when new commits, a retarget or a policy change supersede it (default false: it stays approved). Either way it is commented with who approved it, for which commit and why it no longer applies."
          },
          "summary_template": {
            "type": "string",
            "description": "Template of the change approval summary; the result is made one line and cut to 255 characters (Jira's limit)."
          },
          "description_template": {
            "type": "string"
          },
          "field_mappings": {
            "type": "array",
            "description": "Fields copied from the work items to the change approval.",
            "items": {
              "type": "object",
              "properties": {
                "source_field": {
                  "type": "string"
                },
                "target_field": {
                  "type": "string"
                },
                "merge_strategy": {
                  "type": "string",
                  "enum": [
                    "first",
                    "merge_unique"
                  ]
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "transition_paths": {
            "type": "array",
            "description": "The transitions that reach a status the workflow cannot reach in one step (or that need fields). One path per status.",
            "items": {
              "type": "object",
              "required": [
                "status",
                "steps"
              ],
              "properties": {
                "status": {
                  "type": "string",
                  "description": "The target status (ID or name)."
                },
                "steps": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "transition"
                    ],
                    "properties": {
                      "transition": {
                        "type": "string",
                        "description": "The transition's ID or name."
                      },
                      "fields": {
                        "type": "object",
                        "additionalProperties": true,
                        "description": "Field values the transition screen needs."
                      }
                    }
                  }
                },
                "status_id": {
                  "type": "string",
                  "readOnly": true,
                  "description": "The status's ID on the tracker",
                  "looked up on save.": null
                },
                "status_name": {
                  "type": "string",
                  "readOnly": true
                }
              }
            }
          },
          "priority_map": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "A policy priority to the tracker priority (by name) change approvals are created with; unmapped ones keep the tracker's default."
          },
          "link_type": {
            "type": "string",
            "default": "Relates",
            "description": "The link type between a change approval and its work items."
          }
        }
      }
    }
  }
}
