REST API
The Alien REST API lets your backend manage projects, customers, setup links, releases, and deployments over HTTPS. Use it when your product needs to drive Alien directly, for example to create a setup link when a customer clicks Deploy or to show deployment status on a settings page.
curl "https://api.alien.dev/v1/deployments?project=acme&limit=20" \
-H "Authorization: Bearer $ALIEN_API_KEY"For TypeScript, use the typed platform API client. The endpoint pages in this section are generated from the OpenAPI document at /openapi.json.
Base URL
https://api.alien.devAll endpoints are under /v1. Requests and responses are JSON.
Authentication
Send an API key as a Bearer token:
Authorization: Bearer ax_...Create keys under Settings → API Keys in the dashboard, or with alien api-keys create. Every key belongs to one workspace, so you don't need to pass the workspace query parameter. If you send it, it must match the key's workspace.
Keep keys in server-side secret storage. Never send one to a browser.
Scopes and roles
A key has one scope, and a role within that scope. Pick the narrowest one that does the job.
| Scope | Roles | Typical use |
|---|---|---|
workspace | workspace.viewer, workspace.member, workspace.admin | Automation across every project in a workspace. |
project | project.viewer, project.developer, project.admin | Your backend or CI: create setup links, publish releases, read deployments. |
project (services) | project.encryption, project.ai-gateway, project.sandbox-gateway, project.remote-bindings | A hosted app that calls the Customer-managed keys API, the AI Gateway, Remote Sandboxes, or remote bindings. |
deployment | deployment.viewer, deployment.manager, deployment.dynamic-container-manager, deployment.telemetry-writer | Access to one deployment, such as sending it commands. |
deployment-group | deployment-group.deployer | The token inside a setup link. It can only set up deployments for that customer. |
OAuth 2.0
Interactive clients, including alien login, use the OAuth 2.0 authorization code flow with PKCE (https://api.alien.dev/auth/oauth2/authorize and /auth/oauth2/token). Requests made with a user token must name the workspace with ?workspace=<name> or the x-alien-workspace header.
Customers and external IDs
A customer is a deployment group. Each group can carry an external ID: your own tenant ID, case-sensitive, up to 128 characters of letters, digits, ., _, ~, and -. Use it to look customers up without storing Alien IDs:
| Task | Endpoint |
|---|---|
| Create a setup link for a tenant (creates the group if needed) | POST /v1/deployment-groups/setup-links |
| Get or create the group for a tenant | PUT /v1/deployment-groups/by-external-id |
| Find the group for a tenant | GET /v1/deployment-groups/by-external-id |
| List that customer's deployments | GET /v1/deployments?deploymentGroup=<id> |
The hosted AI Gateway and the Customer-managed keys API use the same external ID in the X-Alien-External-ID header to pick the customer's models or key.
Pagination
List endpoints take limit (1 to 100, default 20) and cursor, and return:
{
"items": [],
"nextCursor": "eyJpZCI6ImRlcF8..."
}Pass nextCursor as cursor to get the next page. nextCursor is null on the last page.
Errors
Errors return a 4xx or 5xx status and a JSON body:
{
"code": "NOT_FOUND",
"message": "Deployment dep_123 not found",
"retryable": false,
"internal": false,
"hint": null,
"requestId": "req_..."
}| Field | Meaning |
|---|---|
code | Stable, machine-readable error type. Branch on this, not on message. |
message | Human-readable description. |
retryable | true when the same request may succeed later. Retry with backoff. |
internal | true for server-side errors. The message then contains no details. |
hint | Optional next step. |
context | Optional structured details, such as validation errors. |
requestId | Include it when you contact support. |
Endpoint groups
The sidebar lists every endpoint group. Most integrations use these:
- Setup links and Deployment groups: onboard customers.
- Deployments: status, pinning, channels, inputs, retry.
- Releases and Release channels: publish and promote.
- Commands and Operations: run work inside a deployment.
- API keys: create and revoke keys.