Deploys

Trigger and monitor deployments for your Release applications.

Base URL: https://api.release.com

---

List Deploys

Retrieve all deploys across environments for a given app.

Note: This endpoint returns all deploys across all environments for the app.

Endpoint

GET /apps/{appId}/pipelines

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app

Status Codes

Status	Description
200	Successfully retrieved deploys
401	Unauthorized — invalid or missing authentication headers
404	App not found

Example Responses

200 OK

The response is a raw JSON array (not wrapped in a data key).

[
  {
    "id": 42,
    "aasm_state": "done",
    "commit_short": "a1b2c3d",
    "commit_long": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "started_at": "2025-06-01T12:00:00Z",
    "total_duration": 245.3,
    "stages": [
      {
        "name": "build",
        "aasm_state": "done",
        "had_errors": false
      },
      {
        "name": "deploy",
        "aasm_state": "done",
        "had_errors": false
      }
    ]
  }
]

---

Create Deploy

Trigger a new deploy for a specific environment.

Endpoint

POST /apps/{appId}/spaces/{envId}/pipelines

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app
envId	string (hashid)	Yes	The unique identifier of the environment

Status Codes

Status	Description
201	Deploy successfully created
401	Unauthorized — invalid or missing authentication headers
404	App or environment not found

Example Responses

201 Created

{
  "id": 43,
  "aasm_state": "ready",
  "commit_short": "b2c3d4e",
  "commit_long": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
  "started_at": null,
  "total_duration": null,
  "stages": [
    {
      "name": "build",
      "aasm_state": "ready",
      "had_errors": false
    }
  ]
}

---

Get Deploy

Retrieve details for a specific deploy.

Note: Both integer IDs and hashids are supported for appId and id. The web UI uses hashids in URLs (e.g., deploys/9x4cxnxw3).

Endpoint

GET /apps/{appId}/pipelines/{id}

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app (integer or hashid)
id	integer or string (hashid)	Yes	The deploy identifier (integer or hashid)

Status Codes

Status	Description
200	Successfully retrieved deploy
401	Unauthorized — invalid or missing authentication headers
404	Deploy not found

Response Body

Field	Type	Description
id	integer	Deploy identifier
aasm_state	string	One of: ready, running, done, errored
commit_short	string	Abbreviated commit SHA
commit_long	string	Full commit SHA
started_at	string (ISO 8601) or null	When the deploy started
total_duration	number or null	Duration in seconds
stages	array	Nested stage objects

Stage fields:

Field	Type	Description
name	string	Stage name
aasm_state	string	One of: ready, running, done
had_errors	boolean	Whether the stage encountered errors

Example Responses

200 OK

{
  "id": 42,
  "aasm_state": "done",
  "commit_short": "a1b2c3d",
  "commit_long": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "started_at": "2025-06-01T12:00:00Z",
  "total_duration": 245.3,
  "stages": [
    {
      "name": "build",
      "aasm_state": "done",
      "had_errors": false
    },
    {
      "name": "deploy",
      "aasm_state": "done",
      "had_errors": false
    }
  ]
}

---

State Lifecycle

Pipeline States

ready → running → done | errored

State	Description
ready	Deploy is queued and has not started
running	Deploy is currently executing
done	Deploy completed successfully
errored	Deploy failed with errors

Stage States

ready → running → done

State	Description
ready	Stage has not started
running	Stage is currently executing
done	Stage completed (check had_errors for error status)