--- title: "List the deployments that satisfy the provided filters. We accept new deployment notifications at `/events/deployments`." method: POST path: "/filter/deployments" tags: ["filter", "default"] --- # List the deployments that satisfy the provided filters. We accept new deployment notifications at \`/events/deployments\`. `POST /filter/deployments` ## Request - Base URL: `{{ server_url }}/v1` - URL: `{{ server_url }}/v1/filter/deployments` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Request body - FilterDeploymentsRequest: Filters to select the deployments in `/filter/deployments`. - `date_from` string, date, required: Search for the deployments since this date. - `date_to` string, date, required: Search for the deployments until this date. - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`. - `account` integer, required: Session account ID. - `in` RepositoryID[]: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored. - `with` DeploymentWith: Deployment contribution roles. The aggregation is `OR` everywhere. It is possible to mention whole teams using the syntax `{id}` where `id` is a team identifier (see `/teams`). - `pr_author` DeveloperID[]: Authors of deployed pull requests. - `commit_author` DeveloperID[]: Authors of deployed commits. - `releaser` DeveloperID[]: Deployed release publishers. - `pr_labels_include` string[]: At least one of these labels must be present in at least one deployed PR. - `pr_labels_exclude` string[]: None of these labels must be present in each deployed PR. - `jira` JIRAFilter: Filters related to JIRA traits. The aggregation between each filter type is *AND*. - `epics` string[]: JIRA issues must be included in the epics from the list. - `labels_include` string[]: Only issues having at least one label from the list will be included Several labels may be concatenated by a comma `,` so that all of them are required. - `labels_exclude` string[]: Issues having one label from the list will be excluded. - `issue_types` string[]: Issues must have one of the given types, e.g. Bug, Task, Design Document, etc. - `priorities` string[]: Issues must have a priority from the given list. - `projects` string[]: Issues must be contained in a project in the given project keys list. - `status_categories` JIRAStatusCategory[]: The JIRA issues must have a status belonging to one of these categories. - `unmapped` boolean: Select PRs that are not mapped to any JIRA issue. May not be specified with anything else. - `environments` string[]: Deployments must belong to one of these environments. - `conclusions` DeploymentConclusion[]: Deployments must execute with any of these conclusions. - `with_labels` object: Deployments should contain at least one of the specified label values. `null` matches any label value and effectively checks the label existence. - `without_labels` object: Deployments may not contain the specified label values. `null` matches any label value and effectively ensures that the label does not exist. ## Response `200` Deployments that satisfy the specified filters. - FilteredDeployments: Found deployments, response from `/filter/deployments`. - `include` object, required: All people and JIRA issues mentioned in the deployments. - `users` object, required: Mapping user native (e.g., GitHub) login ID -> user details. The users are mentioned in the PRs from "PullRequestSet.data" or in the commits from "FilterCommitsRequest.data". - `jira` object: Mapping JIRA issue ID -> details. - `deployments` FilteredDeployment[], required: List of matched deployments. - `components` DeployedComponent[], required: List of deployed software version. Each item identifies a Git reference in a repository, either a tag or a commit hash. - `repository` string, required: Repository name which uniquely identifies any repository in any service provider. The format matches the repository URL without the protocol part. No ".git" should be appended. We support a special syntax for repository sets: "{reposet id}" adds all the repositories from the given set. - `reference` string, required: We accept three ways to define a Git reference: 1. Tag name. 2. Full commit hash (40 characters). 3. Short commit hash (7 characters). We ignore the reference while we cannot find it in our database. There can be two reasons: - There is a mistake or a typo in the provided data. - We are temporarily unable to synchronize with GitHub. - `environment` string, required: Name of the environment where the deployment happened. - `name` string, nullable: Name of the deployment. If is not specified, we generate our own by the template `--`. The value may not contain \n - new line character, and ' - single quote. - `url` string, url: URL pointing at the internal details of the deployment. - `date_started` string, date-time, required: Timestamp of when the deployment procedure launched. - `date_finished` string, date-time, required: Timestamp of when the deployment procedure completed. - `conclusion` 'SUCCESS' | 'FAILURE' | 'CANCELLED', required: State of the completed deployment. Case-insensitive. - `labels` DeploymentLabels: Arbitrary key-value metadata that associates with the deployment. - `code` object, required: Summary of the deployed code. - `prs` object, required: Number of deployed pull requests per repository. - `lines_prs` object, required: Number of changed lines in the deployed PRs per repository. - `lines_overall` object, required: Number of changed lines in the deployment per repository. - `commits_prs` object, required: Number of deployed PR commits per repository. - `commits_overall` object, required: Number of deployed commits per repository. - `jira` object: JIRA issues mentioned in the deployed PRs. - `prs` DeployedPullRequest[]: List of deployed pull requests. - `repository` string, required: Repository name which uniquely identifies any repository in any service provider. The format matches the repository URL without the protocol part. No ".git" should be appended. We support a special syntax for repository sets: "{reposet id}" adds all the repositories from the given set. - `additions` integer, required - `author` union, required - string: User name which uniquely identifies any developer on any service provider. The format matches the profile URL without the protocol part. - string, nullable - `created` string, date-time, required: When this PR was created. - `deletions` integer, required - `jira` string[]: Mapped JIRA issue IDs. - `number` integer, required - `title` string, required - `releases` DeployedRelease[]: Deployed releases. The format matches `FilteredRelease` except that `prs` is the number of released pull requests instead of a list. - `added_lines` integer, required: Cumulative number of lines inserted since the previous release. - `age` string, required: Time since the previous release /\d+s/. - `commits` integer, required: Number of commits since the previous release. - `commit_authors` DeveloperID[], required: List of released commit authors' logins. - `deleted_lines` integer, required: Cumulative number of lines removed since the previous release. - `name` string, required: Title of the release. - `prs` integer, required: Number of deployed pull requests. - `published` string, date-time, required: When the release was created. - `publisher` string, nullable, required: Login of the person who created the release. - `repository` string, required: Name of the repository where the release exists. - `sha` string, required: Release commit hash. - `url` string, url, required: Link to the release. ## Other responses - `400`: The request is invalid. - `403`: Calling user is not allowed to access the specified repositories. - `404`: The specified account does not exist or the user is not a member. - `422`: The account's installation has not finished yet. ## Changes - **2023-03-03** `f9fdd9fbfc25`: 1 info - added the new optional request property `jira/status_categories` - **2023-01-13** `d08637dcd231`: 2 breaking, 1 info - the `deployments/items/allOf[#/components/schemas/DeploymentNotification]/name` response property's maxLength was unset from `100` for the response status `200` - the `deployments/items/allOf[#/components/schemas/DeploymentNotification]/name` response property's minLength was decreased from `1` to `0` for the response status `200` - the `deployments/items/allOf[#/components/schemas/DeploymentNotification]/name` response's property pattern `^([^'\s]| ){1,100}$` was added for the status `200` - **2022-11-23** `7748d08da314`: 6 breaking, 1 warning, 1 info - removed the required property `deployments/items/allOf[#/components/schemas/DeploymentAnalysis]/prs/items/additions` from the response with the `200` status - removed the required property `deployments/items/allOf[#/components/schemas/DeploymentAnalysis]/prs/items/author` from the response with the `200` status - removed the required property `deployments/items/allOf[#/components/schemas/DeploymentAnalysis]/prs/items/created` from the response with the `200` status - removed the required property `deployments/items/allOf[#/components/schemas/DeploymentAnalysis]/prs/items/deletions` from the response with the `200` status - …4 more - **2022-11-16** `fcf829c0439e`: 1 info - added the new optional request property `jira/priorities` - …earlier changes not shown [Operation history](https://skmtc.dev/athenian/apis/title/changes/filter/deployments/post.md) --- [API](https://skmtc.dev/athenian/apis/title.md) - [All operations](https://skmtc.dev/athenian/apis/title/llms.txt) - [OpenAPI document](https://skmtc.dev/athenian/apis/title/revisions/110c9f7cffdd?raw)