---
title: "Notify about new deployments."
method: POST
path: "/events/deployments"
tags: ["events", "default"]
---

# Notify about new deployments.

`POST /events/deployments`

## Request

- Base URL: `{{ server_url }}/v1`
- URL: `{{ server_url }}/v1/events/deployments`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/athenian/apis/title/docs/events/deployments/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- DeploymentNotification[]
  - `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 `<environment shortcut>-<date>-<hash of the components>`. 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.

## Response `200`

Details about the accepted deployment notifications.

- object
  - `deployments` object[], required: The list of notified deployments.
    - `name` string, required: Name of the deployment.
    - `resolved` boolean, required: Value indicating whether we resolved the received Git reference on the spot. `false` is probably still OK for new references that we haven't synchronized yet.

## 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-27** `5453f6550172`: 2 info
  - response schema `application/json` enum value removed `{}`
  - added the required property `deployments` to the response with the `200` status
- **2023-01-13** `d08637dcd231`: 1 breaking, 1 info
  - added the pattern `^([^'\s]| ){1,100}$` to the request property `items/name`
  - the `items/name` request property's minLength was decreased from `1` to `0`

[Operation history](https://skmtc.dev/athenian/apis/title/changes/events/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)