--- title: "Find releases that were published in the given time fram in the given repositories." method: POST path: "/filter/releases" tags: ["filter", "default"] --- # Find releases that were published in the given time fram in the given repositories. `POST /filter/releases` ## Request - Base URL: `{{ server_url }}/v1` - URL: `{{ server_url }}/v1/filter/releases` - 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 - FilterReleasesRequest: Filters for `/filter/releases`. - `account` integer, required: Session account ID. - `date_from` string, date, required: Updates must be later than or equal to this date. An update is any action that influences the stage assignment. - `date_to` string, date, required: Updates must be earlier than or equal to this date. An update is any action that influences the stage assignment. - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`. - `in` RepositoryID[]: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored. - `with` ReleaseWith: Release 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 released pull requests. - `commit_author` DeveloperID[]: Authors of released commits. - `releaser` DeveloperID[]: Release publishers. - `labels_include` string[]: At least one of these labels must be present in at least one released PR. - `labels_exclude` string[]: PRs with these labels are excluded from `ReleaseSet.data.prs`. - `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. ## Response `200` Repositories that were updated within the given timeframe. - ReleaseSet: Release metadata and contributor user details. - `include` object: Mentioned 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` object: Mapping deployment names to their details. - `data` FilteredRelease[]: List of matching release metadata. - `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. - `deployments` string[]: Deployments with this release. - `name` string, required: Title of the release. - `prs` ReleasedPullRequest[], required: List of released pull requests. - `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 - `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. - `424`: One or more logical repositories miss the release settings. ## 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 `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response property's maxLength was unset from `100` for the response status `200` - the `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response property's minLength was decreased from `1` to `0` for the response status `200` - the `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response's property pattern `^([^'\s]| ){1,100}$` was added for the status `200` [Operation history](https://skmtc.dev/athenian/apis/title/changes/filter/releases/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)