Commands

Bootstrap Commands

Resolve a deployment's current manager and mint a five-minute command capability. Sender tokens can dispatch and observe commands only for this deployment. Receiver tokens can lease and complete commands only for the resolved Container or Daemon target.

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

deploymentId*string

Unique identifier for the deployment.

Matchdep_[0-9a-z]{28}$

role*"sender"

Value in

"sender"

Response Body

`application/json`

curl -X POST "https://example.com/v1/commands/bootstrap" \  -H "Content-Type: application/json" \  -d '{    "deploymentId": "dep_0c29fq4a2yjb7kx3smwdgxlc",    "role": "sender"  }'

{  "managerUrl": "http://example.com",  "token": "string",  "expiresAt": "2019-08-24T14:15:22Z",  "target": {    "resourceId": "string",    "resourceType": "container"  }}

List Commands

Retrieve commands. Use for dashboard analytics and command history.

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?string

Filter by project ID or name.

Lengthlength <= 100

deploymentId?string

Filter by deployment ID

Matchdep_[0-9a-z]{28}$

state?string

Filter by command state

Value in

"PENDING_UPLOAD"
"PENDING"
"DISPATCHED"
"SUCCEEDED"
"FAILED"
"EXPIRED"

name?string

Filter by command name

Lengthlength <= 255

search?string

Search commands by name

Lengthlength <= 256

createdAfter?|

Filter commands created after this date (ISO 8601)

Formatdate-time

createdBefore?|

Filter commands created before this date (ISO 8601)

Formatdate-time

include?array<>

Optional fields to include: deployment, project

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`

curl -X GET "https://example.com/v1/commands?project=my-project"

{  "items": [    {      "id": "cmd_2sxjXxvOYct7IohT3ukliAzf",      "deploymentId": "dep_0c29fq4a2yjb7kx3smwdgxlc",      "projectId": "prj_mcytp6z3j91f7tn5ryqsfwtr",      "workspaceId": "ws_It13CUaGEhLLAB87simX0",      "name": "string",      "state": "PENDING_UPLOAD",      "deploymentModel": "push",      "target": {        "resourceId": "string",        "resourceType": "worker"      },      "attempt": 0,      "deadline": "2019-08-24T14:15:22Z",      "requestSizeBytes": 0,      "responseSizeBytes": 0,      "createdAt": "2019-08-24T14:15:22Z",      "dispatchedAt": "2019-08-24T14:15:22Z",      "completedAt": "2019-08-24T14:15:22Z",      "error": {        "property1": null,        "property2": null      },      "result": null,      "deployment": {        "id": "dep_0c29fq4a2yjb7kx3smwdgxlc",        "name": "string",        "deploymentGroup": {          "id": "string",          "name": "string"        },        "platform": "aws",        "environmentInfo": {          "accountId": "string",          "region": "string",          "platform": "aws"        },        "managerId": "string",        "managerUrl": "http://example.com",        "managerName": "string",        "managerIsSystem": true      },      "project": {        "id": "prj_mcytp6z3j91f7tn5ryqsfwtr",        "name": "string"      }    }  ],  "nextCursor": "string"}

Create Command

Create command metadata. Called by manager when processing commands. Returns project info for routing decisions.

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.

deploymentId*string

Target deployment ID

Matchdep_[0-9a-z]{28}$

name*string

Command name (e.g., 'analyze-repository')

Length1 <= length <= 255

params?unknown

Command parameters for public invocation

target?string

Resource id the command is addressed to. Required when the deployment has more than one command-capable resource.

Lengthlength <= 255

initialState?string

Initial state (PENDING_UPLOAD if params require upload, PENDING if inline)

Value in

"PENDING_UPLOAD"
"PENDING"
"DISPATCHED"
"SUCCEEDED"
"FAILED"
"EXPIRED"

deadline?|

Optional deadline for command execution

Formatdate-time

requestSizeBytes?number

Size of command params in bytes

Range0 < value

Response Body

`application/json`

curl -X POST "https://example.com/v1/commands" \  -H "Content-Type: application/json" \  -d '{    "deploymentId": "dep_0c29fq4a2yjb7kx3smwdgxlc",    "name": "string"  }'

{  "id": "cmd_2sxjXxvOYct7IohT3ukliAzf",  "projectId": "string",  "deploymentModel": "push",  "target": {    "resourceId": "string",    "resourceType": "worker"  },  "deliveryMode": "push"}

List Command Names

List distinct command names. Use for filter dropdowns in the dashboard.

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?string

Filter by project ID or name.

Lengthlength <= 100

search?string

Search command names (prefix match)

Lengthlength <= 255

Response Body

`application/json`

curl -X GET "https://example.com/v1/commands/names?project=my-project"

{  "names": [    "string"  ]}

List Command Deployments

List distinct deployments that have commands, including deployment group info. Use for filter dropdowns in the dashboard.

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?string

Filter by project ID or name.

Lengthlength <= 100

search?string

Search deployment or deployment group names

Lengthlength <= 255

Response Body

`application/json`

curl -X GET "https://example.com/v1/commands/deployments?project=my-project"

{  "deployments": [    {      "id": "dep_0c29fq4a2yjb7kx3smwdgxlc",      "name": "string",      "deploymentGroup": {        "id": "string",        "name": "string"      }    }  ]}

Resolve Command Target

Resolve which resource a command for this deployment would be addressed to, and how it would be delivered. Fails when the deployment has no command-capable resources, or more than one and no explicit target was named.

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

deploymentId*string

Deployment to resolve the target for

Matchdep_[0-9a-z]{28}$

target?string

Explicit resource id to resolve; must be a command-capable resource

Lengthlength <= 255

Response Body

`application/json`

curl -X GET "https://example.com/v1/commands/target?deploymentId=dep_0c29fq4a2yjb7kx3smwdgxlc"

{  "target": {    "resourceId": "string",    "resourceType": "worker"  },  "deliveryMode": "push"}

Get Command

Retrieve a command 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 command.

Matchcmd_[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

Response Body

`application/json`

curl -X GET "https://example.com/v1/commands/cmd_2sxjXxvOYct7IohT3ukliAzf"

{  "id": "cmd_2sxjXxvOYct7IohT3ukliAzf",  "deploymentId": "dep_0c29fq4a2yjb7kx3smwdgxlc",  "projectId": "prj_mcytp6z3j91f7tn5ryqsfwtr",  "workspaceId": "ws_It13CUaGEhLLAB87simX0",  "name": "string",  "state": "PENDING_UPLOAD",  "deploymentModel": "push",  "target": {    "resourceId": "string",    "resourceType": "worker"  },  "attempt": 0,  "deadline": "2019-08-24T14:15:22Z",  "requestSizeBytes": 0,  "responseSizeBytes": 0,  "createdAt": "2019-08-24T14:15:22Z",  "dispatchedAt": "2019-08-24T14:15:22Z",  "completedAt": "2019-08-24T14:15:22Z",  "error": {    "property1": null,    "property2": null  },  "result": null}

Update Command

Update command state. Called by manager when command is dispatched or completes.

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 command.

Matchcmd_[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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

state?string

New command state

Value in

"PENDING_UPLOAD"
"PENDING"
"DISPATCHED"
"SUCCEEDED"
"FAILED"
"EXPIRED"

attempt?number

Current attempt number

Range0 < value

dispatchedAt?|

When command was dispatched

Formatdate-time

completedAt?|

When command completed

Formatdate-time

responseSizeBytes?|

Size of response in bytes

Range0 < value

error?|

Error details if failed

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/commands/cmd_2sxjXxvOYct7IohT3ukliAzf" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "cmd_2sxjXxvOYct7IohT3ukliAzf",  "deploymentId": "dep_0c29fq4a2yjb7kx3smwdgxlc",  "projectId": "prj_mcytp6z3j91f7tn5ryqsfwtr",  "workspaceId": "ws_It13CUaGEhLLAB87simX0",  "name": "string",  "state": "PENDING_UPLOAD",  "deploymentModel": "push",  "target": {    "resourceId": "string",    "resourceType": "worker"  },  "attempt": 0,  "deadline": "2019-08-24T14:15:22Z",  "requestSizeBytes": 0,  "responseSizeBytes": 0,  "createdAt": "2019-08-24T14:15:22Z",  "dispatchedAt": "2019-08-24T14:15:22Z",  "completedAt": "2019-08-24T14:15:22Z",  "error": {    "property1": null,    "property2": null  },  "result": null}

Dispatch Command

Atomically mark a command DISPATCHED unless it is already terminal. Returns whether the transition was applied.

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 command.

Matchcmd_[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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

dispatchedAt*string

When the command was dispatched

Formatdate-time

Response Body

`application/json`

curl -X POST "https://example.com/v1/commands/cmd_2sxjXxvOYct7IohT3ukliAzf/dispatch" \  -H "Content-Type: application/json" \  -d '{    "dispatchedAt": "2019-08-24T14:15:22Z"  }'

{  "updated": true}

Complete Command

Atomically transition a command to a terminal state (SUCCEEDED, FAILED, or EXPIRED) unless it is already terminal. Returns whether the transition was applied.

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 command.

Matchcmd_[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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

state*string

Terminal state to transition to

Value in

"SUCCEEDED"
"FAILED"
"EXPIRED"

completedAt*string

When the command completed

Formatdate-time

responseSizeBytes?|

Size of response in bytes

Range0 < value

error?|

Error details if failed

Response Body

`application/json`

curl -X POST "https://example.com/v1/commands/cmd_2sxjXxvOYct7IohT3ukliAzf/complete" \  -H "Content-Type: application/json" \  -d '{    "state": "SUCCEEDED",    "completedAt": "2019-08-24T14:15:22Z"  }'

{  "updated": true}

Increment Command Attempt

Atomically increment the command's attempt counter and return the new value.

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 command.

Matchcmd_[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

Response Body

`application/json`

curl -X POST "https://example.com/v1/commands/cmd_2sxjXxvOYct7IohT3ukliAzf/increment-attempt"

{  "attempt": 0}

200application/json

400application/json

401application/json

403application/json

404application/json

422application/json

500application/json

503application/json

200application/json

500application/json

201application/json

400application/json

404application/json

409application/json

422application/json

500application/json

503application/json

200application/json

500application/json

200application/json

500application/json

200application/json

404application/json

409application/json

422application/json

500application/json

200application/json

404application/json

500application/json

200application/json

404application/json

500application/json

200application/json

404application/json

500application/json

200application/json

404application/json

500application/json

200application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`