Docs

Releases

List Releases

GET
/v1/releases

Retrieve all releases.

Authorization

apiKey
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. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must match the key's workspace.

Match^(?!ws[-_])[a-z0-9](-?[a-z0-9])*$
Length4 <= length <= 100
include?array<>

Optional fields to include: project, rollout

search?|

Search releases by commit message, branch, SHA, or release ID

Lengthlength <= 256
branch?|

Filter by git branch (commitRef)

Lengthlength <= 256
author?|

Filter by commit author login or name

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

curl -X GET "https://example.com/v1/releases?project=my-project"
{  "items": [    {      "id": "rel_WbhQgksrawSKIpEN0NAssHX9",      "projectId": "string",      "version": "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

apiKey
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. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must match the key's workspace.

Match^(?!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

curl -X POST "https://example.com/v1/releases" \  -H "Content-Type: application/json" \  -d '{    "project": "string"  }'
{  "id": "rel_WbhQgksrawSKIpEN0NAssHX9",  "projectId": "string",  "version": "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.

Authorization

apiKey
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. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must match the key's workspace.

Match^(?!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.

Authorization

apiKey
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. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must match the key's workspace.

Match^(?!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

apiKey
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. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must match the key's workspace.

Match^(?!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",  "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

apiKey
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. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must match the key's workspace.

Match^(?!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

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/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      }    }  ],  "nextCursor": "string",  "stateCounts": {    "updated": 0,    "updating": 0,    "failed": 0,    "pending": 0,    "pinned-other": 0,    "superseded": 0,    "on-other": 0  }}

Promote Release

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

Authorization

apiKey
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. Required for user/session/OAuth requests. Optional for API keys because API keys are workspace-scoped; if provided with an API key, it must match the key's workspace.

Match^(?!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"}

Packages

Previous Page

Release Channels

Next Page