Docs

Releases

List Releases

GET
/v1/releases

Retrieve all releases.

Authorization

AuthorizationBearer <token>

API key for authentication, must be provided as a Bearer token. Generate an API key at https://alien.dev/api-keys

In: header

Query Parameters

project?|

Filter by project ID or name.

channel?|

Filter to releases promoted to this channel. Defaults to production.

Match^[a-z][a-z0-9-]*$
Length1 <= length <= 63
allChannels?string
Default"false"

Value in

  • "true"
  • "false"
workspace?string

Workspace name or ID. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must identify the key's workspace.

Match^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$
Length4 <= length <= 100
include?array<>

Optional fields to include: project, rollout

search?|

Search releases by release ID or title, and by commit message, branch, SHA, or author when the caller can read source-control details

Lengthlength <= 256
branch?|

Filter by git branch (commitRef). Rejected for deployment and deployment-group tokens.

Lengthlength <= 256
author?|

Filter by commit author login or name. Rejected for deployment and deployment-group tokens.

Lengthlength <= 256
createdAfter?|

Filter releases created after this date (ISO 8601)

Formatdate-time
createdBefore?|

Filter releases created before this date (ISO 8601)

Formatdate-time
limit?integer

Maximum number of items to return per page

Range1 <= value <= 100
Default20
cursor?string

Cursor for pagination - omit for first page

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/releases?project=my-project"
{  "items": [    {      "id": "rel_WbhQgksrawSKIpEN0NAssHX9",      "projectId": "string",      "version": "string",      "title": "string",      "gitMetadata": {        "commitSha": "dc36199b2234c6586ebe05ec94078a895c707e29",        "commitMessage": "add method to measure Interaction to Next Paint (INP) (#36490)",        "commitRef": "main",        "commitDate": "2026-03-16T12:00:00Z",        "dirty": true,        "remoteUrl": "https://github.com/alienplatform/alien",        "commitAuthorName": "John Doe",        "commitAuthorEmail": "john@example.com",        "commitAuthorLogin": "johndoe",        "commitAuthorAvatarUrl": "https://github.com/johndoe.png",        "provider": {          "type": "github",          "org": "string",          "repo": "string"        }      },      "createdAt": "2019-08-24T14:15:22Z",      "stack": {        "aws": null,        "gcp": null,        "azure": null,        "kubernetes": null,        "machines": null,        "local": null,        "test": null      },      "setupFingerprints": {        "property1": {          "target": "string",          "fingerprint": "string",          "version": 1        },        "property2": {          "target": "string",          "fingerprint": "string",          "version": 1        }      },      "rootDirectory": "string",      "createdByUserId": "string",      "workspaceId": "string",      "currentChannels": [        "string"      ],      "commitUrl": "http://example.com",      "project": {        "id": "string",        "name": "string"      },      "rollout": {        "updatedCount": 0,        "pendingCount": 0,        "avgDurationMs": 0      },      "createdBy": {        "id": "string",        "name": "string",        "email": "string",        "image": "string"      }    }  ],  "nextCursor": "string"}

Create Release

POST
/v1/releases

Create a new release.

Authorization

AuthorizationBearer <token>

API key for authentication, must be provided as a Bearer token. Generate an API key at https://alien.dev/api-keys

In: header

Query Parameters

workspace?string

Workspace name or ID. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must identify the key's workspace.

Match^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$
Length4 <= length <= 100

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/releases" \  -H "Content-Type: application/json" \  -d '{    "project": "string"  }'
{  "id": "rel_WbhQgksrawSKIpEN0NAssHX9",  "projectId": "string",  "version": "string",  "title": "string",  "gitMetadata": {    "commitSha": "dc36199b2234c6586ebe05ec94078a895c707e29",    "commitMessage": "add method to measure Interaction to Next Paint (INP) (#36490)",    "commitRef": "main",    "commitDate": "2026-03-16T12:00:00Z",    "dirty": true,    "remoteUrl": "https://github.com/alienplatform/alien",    "commitAuthorName": "John Doe",    "commitAuthorEmail": "john@example.com",    "commitAuthorLogin": "johndoe",    "commitAuthorAvatarUrl": "https://github.com/johndoe.png",    "provider": {      "type": "github",      "org": "string",      "repo": "string"    }  },  "createdAt": "2019-08-24T14:15:22Z",  "stack": {    "aws": null,    "gcp": null,    "azure": null,    "kubernetes": null,    "machines": null,    "local": null,    "test": null  },  "setupFingerprints": {    "property1": {      "target": "string",      "fingerprint": "string",      "version": 1    },    "property2": {      "target": "string",      "fingerprint": "string",      "version": 1    }  },  "rootDirectory": "string",  "createdByUserId": "string",  "workspaceId": "string"}

List Release Branches

GET
/v1/releases/branches

List distinct git branches across releases. Used for filter dropdowns. Empty for deployment and deployment-group tokens.

Authorization

AuthorizationBearer <token>

API key for authentication, must be provided as a Bearer token. Generate an API key at https://alien.dev/api-keys

In: header

Query Parameters

workspace?string

Workspace name or ID. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must identify the key's workspace.

Match^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$
Length4 <= length <= 100
project?|

Filter by project ID or name.

search?|

Search branches by name (case-insensitive contains)

Lengthlength <= 256
limit?integer

Maximum number of branches to return

Range1 <= value <= 100
Default50

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/releases/branches?project=my-project"
{  "items": [    "string"  ]}

List Release Authors

GET
/v1/releases/authors

List distinct commit authors across releases. Used for filter dropdowns. Empty for deployment and deployment-group tokens.

Authorization

AuthorizationBearer <token>

API key for authentication, must be provided as a Bearer token. Generate an API key at https://alien.dev/api-keys

In: header

Query Parameters

workspace?string

Workspace name or ID. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must identify the key's workspace.

Match^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$
Length4 <= length <= 100
project?|

Filter by project ID or name.

search?|

Search authors by login or name (case-insensitive contains)

Lengthlength <= 256
limit?integer

Maximum number of authors to return

Range1 <= value <= 100
Default50

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/releases/authors?project=my-project"
{  "items": [    {      "login": "string",      "name": "string",      "avatarUrl": "http://example.com"    }  ]}

Get Release

GET
/v1/releases/{id}

Retrieve a release by ID.

Authorization

AuthorizationBearer <token>

API key for authentication, must be provided as a Bearer token. Generate an API key at https://alien.dev/api-keys

In: header

Path Parameters

id*string

Unique identifier for the release.

Matchrel_[0-9a-zA-Z]{28}$

Query Parameters

workspace?string

Workspace name or ID. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must identify the key's workspace.

Match^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$
Length4 <= length <= 100
include?array<>

Optional fields to include: project, rollout

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/releases/rel_WbhQgksrawSKIpEN0NAssHX9"
{  "id": "rel_WbhQgksrawSKIpEN0NAssHX9",  "projectId": "string",  "version": "string",  "title": "string",  "gitMetadata": {    "commitSha": "dc36199b2234c6586ebe05ec94078a895c707e29",    "commitMessage": "add method to measure Interaction to Next Paint (INP) (#36490)",    "commitRef": "main",    "commitDate": "2026-03-16T12:00:00Z",    "dirty": true,    "remoteUrl": "https://github.com/alienplatform/alien",    "commitAuthorName": "John Doe",    "commitAuthorEmail": "john@example.com",    "commitAuthorLogin": "johndoe",    "commitAuthorAvatarUrl": "https://github.com/johndoe.png",    "provider": {      "type": "github",      "org": "string",      "repo": "string"    }  },  "createdAt": "2019-08-24T14:15:22Z",  "stack": {    "aws": null,    "gcp": null,    "azure": null,    "kubernetes": null,    "machines": null,    "local": null,    "test": null  },  "setupFingerprints": {    "property1": {      "target": "string",      "fingerprint": "string",      "version": 1    },    "property2": {      "target": "string",      "fingerprint": "string",      "version": 1    }  },  "rootDirectory": "string",  "createdByUserId": "string",  "workspaceId": "string",  "currentChannels": [    "string"  ],  "commitUrl": "http://example.com",  "project": {    "id": "string",    "name": "string"  },  "rollout": {    "updatedCount": 0,    "pendingCount": 0,    "avgDurationMs": 0  },  "createdBy": {    "id": "string",    "name": "string",    "email": "string",    "image": "string"  }}

List Release Deployments

GET
/v1/releases/{id}/deployments

List the project's deployments with their rollout state relative to this release.

Authorization

AuthorizationBearer <token>

API key for authentication, must be provided as a Bearer token. Generate an API key at https://alien.dev/api-keys

In: header

Path Parameters

id*string

Unique identifier for the release.

Matchrel_[0-9a-zA-Z]{28}$

Query Parameters

workspace?string

Workspace name or ID. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must identify the key's workspace.

Match^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$
Length4 <= length <= 100
state?array<>

Filter deployments by rollout state

deploymentGroup?string

Filter by deployment group ID or name

channel?string

Only deployments that follow this channel, each with the effect of promoting this release to it

Match^[a-z][a-z0-9-]*$
Length1 <= length <= 63
effectScope?string

Whether effect filters describe promotion policy or the current rollout. Defaults to promotion.

Value in

  • "promotion"
  • "rollout"
effect?string

Filter deployments by the effect of promoting this release to their channel

Value in

  • "updates"
  • "unconfirmed"
  • "retries"
  • "already-on"
  • "pinned"
  • "customer-applies"
  • "waits-for-approval"
  • "waits-for-owner"
  • "waits-for-inputs"
  • "not-affected"
limit?integer

Maximum number of items to return per page

Range1 <= value <= 100
Default20
cursor?string

Cursor for pagination - omit for first page

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/releases/rel_WbhQgksrawSKIpEN0NAssHX9/deployments"
{  "items": [    {      "id": "dep_0c29fq4a2yjb7kx3smwdgxlc",      "name": "string",      "status": "pending",      "platform": "aws",      "environmentInfo": {        "accountId": "string",        "region": "string",        "platform": "aws"      },      "deploymentGroup": {        "id": "dg_r27ict8c7vcgsumpj90ackf7b",        "name": "prod-us-east-1",        "externalId": "ext_example_01"      },      "currentReleaseId": "rel_WbhQgksrawSKIpEN0NAssHX9",      "desiredReleaseId": "rel_WbhQgksrawSKIpEN0NAssHX9",      "pinnedReleaseId": "rel_WbhQgksrawSKIpEN0NAssHX9",      "lastHeartbeatAt": "2019-08-24T14:15:22Z",      "rolloutState": "updated",      "releasedAt": "2019-08-24T14:15:22Z",      "durationMs": 0,      "error": {        "code": "string",        "context": null,        "hint": "string",        "httpStatusCode": 100,        "internal": true,        "message": "string",        "retryable": false,        "source": null      },      "promotionEffect": "updates"    }  ],  "nextCursor": "string",  "stateCounts": {    "updated": 0,    "updating": 0,    "failed": 0,    "pending": 0,    "waiting-on-owner": 0,    "waiting-on-inputs": 0,    "pinned-other": 0,    "superseded": 0,    "on-other": 0  }}
GET
/v1/releases/{id}/channels

List the project's release channels with what each runs now and what promoting this release to it would change.

Authorization

AuthorizationBearer <token>

API key for authentication, must be provided as a Bearer token. Generate an API key at https://alien.dev/api-keys

In: header

Path Parameters

id*string

Unique identifier for the release.

Matchrel_[0-9a-zA-Z]{28}$

Query Parameters

workspace?string

Workspace name or ID. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must identify the key's workspace.

Match^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$
Length4 <= length <= 100

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/releases/rel_WbhQgksrawSKIpEN0NAssHX9/channels"
{  "items": [    {      "channel": "string",      "currentRelease": {        "id": "rel_WbhQgksrawSKIpEN0NAssHX9",        "version": "string",        "title": "string",        "gitMetadata": {          "commitSha": "dc36199b2234c6586ebe05ec94078a895c707e29",          "commitMessage": "add method to measure Interaction to Next Paint (INP) (#36490)",          "commitRef": "main",          "commitDate": "2026-03-16T12:00:00Z",          "dirty": true,          "remoteUrl": "https://github.com/alienplatform/alien",          "commitAuthorName": "John Doe",          "commitAuthorEmail": "john@example.com",          "commitAuthorLogin": "johndoe",          "commitAuthorAvatarUrl": "https://github.com/johndoe.png",          "provider": {            "type": "github",            "org": "string",            "repo": "string"          }        },        "createdAt": "2019-08-24T14:15:22Z"      },      "runsThisRelease": true,      "rollbackRelease": {        "id": "rel_WbhQgksrawSKIpEN0NAssHX9",        "version": "string",        "title": "string",        "gitMetadata": {          "commitSha": "dc36199b2234c6586ebe05ec94078a895c707e29",          "commitMessage": "add method to measure Interaction to Next Paint (INP) (#36490)",          "commitRef": "main",          "commitDate": "2026-03-16T12:00:00Z",          "dirty": true,          "remoteUrl": "https://github.com/alienplatform/alien",          "commitAuthorName": "John Doe",          "commitAuthorEmail": "john@example.com",          "commitAuthorLogin": "johndoe",          "commitAuthorAvatarUrl": "https://github.com/johndoe.png",          "provider": {            "type": "github",            "org": "string",            "repo": "string"          }        },        "createdAt": "2019-08-24T14:15:22Z"      },      "deploymentCount": 0,      "rolloutEffects": {        "updates": 0,        "unconfirmed": 0,        "retries": 0,        "already-on": 0,        "pinned": 0,        "customer-applies": 0,        "waits-for-approval": 0,        "waits-for-owner": 0,        "waits-for-inputs": 0,        "not-affected": 0      },      "effects": {        "updates": 0,        "unconfirmed": 0,        "retries": 0,        "already-on": 0,        "pinned": 0,        "customer-applies": 0,        "waits-for-approval": 0,        "waits-for-owner": 0,        "waits-for-inputs": 0,        "not-affected": 0      }    }  ]}

Promote Release

POST
/v1/release-channels/{name}/promote

Authorization

AuthorizationBearer <token>

API key for authentication, must be provided as a Bearer token. Generate an API key at https://alien.dev/api-keys

In: header

Path Parameters

name*string
Match^[a-z][a-z0-9-]*$
Length1 <= length <= 63

Query Parameters

workspace?string

Workspace name or ID. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must identify the key's workspace.

Match^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$
Length4 <= length <= 100
project*string

Filter by project ID or name.

Lengthlength <= 100

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/release-channels/string/promote?project=my-project" \  -H "Content-Type: application/json" \  -d '{    "releaseId": "rel_WbhQgksrawSKIpEN0NAssHX9"  }'
{  "workspaceId": "ws_It13CUaGEhLLAB87simX0",  "projectId": "prj_mcytp6z3j91f7tn5ryqsfwtr",  "name": "string",  "currentReleaseId": "rel_WbhQgksrawSKIpEN0NAssHX9",  "deploymentCount": 0,  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}