Docs

Operations

List Operations Plugins

GET
/v1/operations/plugins

List available operations plugins (builtin + custom) for a project, with their operations and risk tiers.

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

Filter by project ID or name.

Lengthlength <= 100
deployment?string

Only the plugins this deployment declares, at their declared versions.

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/operations/plugins?project=my-project"
{  "plugins": [    {      "name": "string",      "version": "string",      "tier": "read-only",      "builtin": true,      "operations": [        {          "name": "string",          "tier": "read-only",          "description": "string",          "inputSchema": {            "property1": null,            "property2": null          },          "outputSchema": {            "property1": null,            "property2": null          },          "timeoutSeconds": 1,          "retries": {            "maxAttempts": 1,            "intervalSeconds": 0          },          "verification": {            "changes": "string",            "pollOperation": "string",            "pollParamsFromResult": {              "property1": "string",              "property2": "string"            },            "successField": "string",            "successValue": "string",            "retry": {              "maxAttempts": 1,              "intervalSeconds": 0            },            "timeoutSeconds": 1          },          "sensitiveOutput": {            "kind": "none"          },          "requiredPermissions": [            "string"          ],          "permissions": {            "azure": [],            "aws": [              {                "effect": "Allow",                "actions": [                  "string"                ],                "resources": [                  "string"                ],                "condition": {                  "property1": {                    "property1": "string",                    "property2": "string"                  },                  "property2": {                    "property1": "string",                    "property2": "string"                  }                },                "reason": "string"              }            ],            "gcp": [              {                "permissions": [                  "string"                ],                "scope": "projects/${projectName}",                "reason": "string"              }            ]          },          "kubernetesPermissions": {            "schemaVersion": 1,            "rules": [              {                "apiGroup": "string",                "resource": "string",                "verbs": [                  "get"                ],                "resourceNames": [],                "reason": "string"              }            ]          }        }      ]    }  ]}
POST
/v1/operations/plugins

Register a version of a custom operations plugin whose bundle ZIP has already been uploaded to S3 (see POST /plugins/upload-url). Publishing changes no deployment: a release runs the version it declares in operations().

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*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

application/json

application/json

curl -X POST "https://example.com/v1/operations/plugins?project=my-project" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "version": "string",    "uploadId": "string",    "tier": "read-only",    "metadata": {      "name": "string",      "version": "string",      "binaries": {        "amd64": "string"      }    }  }'
{  "name": "string",  "version": "string",  "tier": "read-only"}
POST
/v1/operations/plugins/upload-url

Get a presigned S3 URL to upload a custom operations plugin bundle ZIP. Upload the ZIP with a PUT to the returned url (sending the given Content-Type), then call POST /plugins to register it.

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*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/operations/plugins/upload-url?project=my-project" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "uploadUrl": "http://example.com",  "uploadId": "string",  "contentType": "string"}

Invoke Operation

POST
/v1/operations/invoke

Invoke a plugin operation against a deployment. Honors the approval rules the deployment's release declares in operations().

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*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

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/operations/invoke?project=my-project" \  -H "Content-Type: application/json" \  -d '{    "deploymentId": "string",    "plugin": "string",    "operation": "string"  }'
{  "plugin": "string",  "operation": "string",  "tier": "read-only",  "decision": "auto",  "status": "dispatched",  "commandId": "string"}

List Access Requests

GET
/v1/access-requests

List a project's access requests, newest first.

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

Filter by project ID or name.

Lengthlength <= 100
status?array<>

Filter by status.

deploymentId?string

Filter by deployment ID.

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

Only requests proposed by this investigation's remediation plan.

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/access-requests?project=my-project"
{  "items": [    {      "id": "string",      "requesterKind": "user",      "requesterId": "string",      "requestedExpiresAt": "string",      "deploymentId": "string",      "deployment": {        "id": "string",        "name": "string",        "deploymentGroup": {          "id": "dg_r27ict8c7vcgsumpj90ackf7b",          "name": "prod-us-east-1",          "externalId": "ext_example_01"        }      },      "remediationPlanId": "string",      "agentSessionId": "string",      "title": "string",      "reason": "string",      "commands": [        {          "command": "kubernetes/get-pods",          "summary": "List pods in the ingestion namespace",          "params": {            "pod": "ingester-p4kwm"          },          "tier": "read-only",          "pluginVersion": "string",          "operationContractHash": "string"        }      ],      "operationPattern": "string",      "maxRisk": "read-only",      "debugGrant": {        "tool": "kubectl",        "namespace": "braintrust",        "cloudScope": "123456789012/prod-readonly"      },      "status": "pending-approval",      "approvedUntil": "string",      "createdAt": "string",      "queuedBy": "string",      "queuedAt": "string",      "approvedBy": {        "method": "string",        "actorId": "string",        "at": "string"      },      "deniedBy": {        "actorId": "string",        "at": "string"      },      "revokedBy": {        "actorKind": "user",        "actorId": "string",        "at": "string",        "reason": "string"      },      "approvalChannels": [        "kubectl"      ]    }  ],  "nextCursor": "string"}

Create Access Request

POST
/v1/access-requests

Create an access request — either plan-backed (the exact commands of an investigation plan) or plan-less (a CLI-originated exact operation or wildcard pattern, resolved and frozen here). Plan-backed requests await the engineer gate (status pending-approval); plan-less requests are queued immediately since the requester is asking for their own access (status queued).

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

application/json

curl -X POST "https://example.com/v1/access-requests" \  -H "Content-Type: application/json" \  -d '{    "deploymentId": "string"  }'
{  "id": "string",  "requesterKind": "user",  "requesterId": "string",  "requestedExpiresAt": "string",  "deploymentId": "string",  "deployment": {    "id": "string",    "name": "string",    "deploymentGroup": {      "id": "dg_r27ict8c7vcgsumpj90ackf7b",      "name": "prod-us-east-1",      "externalId": "ext_example_01"    }  },  "remediationPlanId": "string",  "agentSessionId": "string",  "title": "string",  "reason": "string",  "commands": [    {      "command": "kubernetes/get-pods",      "summary": "List pods in the ingestion namespace",      "params": {        "pod": "ingester-p4kwm"      },      "tier": "read-only",      "pluginVersion": "string",      "operationContractHash": "string"    }  ],  "operationPattern": "string",  "maxRisk": "read-only",  "debugGrant": {    "tool": "kubectl",    "namespace": "braintrust",    "cloudScope": "123456789012/prod-readonly"  },  "status": "pending-approval",  "approvedUntil": "string",  "createdAt": "string",  "queuedBy": "string",  "queuedAt": "string",  "approvedBy": {    "method": "string",    "actorId": "string",    "at": "string"  },  "deniedBy": {    "actorId": "string",    "at": "string"  },  "revokedBy": {    "actorKind": "user",    "actorId": "string",    "at": "string",    "reason": "string"  },  "approvalChannels": [    "kubectl"  ]}

Queue Access Request

POST
/v1/access-requests/{id}/queue

Engineer gate — approve a pending access request, queuing it for the operator to materialize. Records who queued it.

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

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

application/json

application/json

curl -X POST "https://example.com/v1/access-requests/string/queue"
{  "id": "string",  "requesterKind": "user",  "requesterId": "string",  "requestedExpiresAt": "string",  "deploymentId": "string",  "deployment": {    "id": "string",    "name": "string",    "deploymentGroup": {      "id": "dg_r27ict8c7vcgsumpj90ackf7b",      "name": "prod-us-east-1",      "externalId": "ext_example_01"    }  },  "remediationPlanId": "string",  "agentSessionId": "string",  "title": "string",  "reason": "string",  "commands": [    {      "command": "kubernetes/get-pods",      "summary": "List pods in the ingestion namespace",      "params": {        "pod": "ingester-p4kwm"      },      "tier": "read-only",      "pluginVersion": "string",      "operationContractHash": "string"    }  ],  "operationPattern": "string",  "maxRisk": "read-only",  "debugGrant": {    "tool": "kubectl",    "namespace": "braintrust",    "cloudScope": "123456789012/prod-readonly"  },  "status": "pending-approval",  "approvedUntil": "string",  "createdAt": "string",  "queuedBy": "string",  "queuedAt": "string",  "approvedBy": {    "method": "string",    "actorId": "string",    "at": "string"  },  "deniedBy": {    "actorId": "string",    "at": "string"  },  "revokedBy": {    "actorKind": "user",    "actorId": "string",    "at": "string",    "reason": "string"  },  "approvalChannels": [    "kubectl"  ],  "kubectlApprove": "string"}

Approve Access Request

POST
/v1/access-requests/{id}/approve

Customer gate — an authenticated workspace member or administrator other than the requester may approve a queued access request. Actor identity comes from authentication; method/source are audit context only.

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

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

application/json

curl -X POST "https://example.com/v1/access-requests/string/approve" \  -H "Content-Type: application/json" \  -d '{    "method": "slack"  }'
{  "id": "string",  "requesterKind": "user",  "requesterId": "string",  "requestedExpiresAt": "string",  "deploymentId": "string",  "deployment": {    "id": "string",    "name": "string",    "deploymentGroup": {      "id": "dg_r27ict8c7vcgsumpj90ackf7b",      "name": "prod-us-east-1",      "externalId": "ext_example_01"    }  },  "remediationPlanId": "string",  "agentSessionId": "string",  "title": "string",  "reason": "string",  "commands": [    {      "command": "kubernetes/get-pods",      "summary": "List pods in the ingestion namespace",      "params": {        "pod": "ingester-p4kwm"      },      "tier": "read-only",      "pluginVersion": "string",      "operationContractHash": "string"    }  ],  "operationPattern": "string",  "maxRisk": "read-only",  "debugGrant": {    "tool": "kubectl",    "namespace": "braintrust",    "cloudScope": "123456789012/prod-readonly"  },  "status": "pending-approval",  "approvedUntil": "string",  "createdAt": "string",  "queuedBy": "string",  "queuedAt": "string",  "approvedBy": {    "method": "string",    "actorId": "string",    "at": "string"  },  "deniedBy": {    "actorId": "string",    "at": "string"  },  "revokedBy": {    "actorKind": "user",    "actorId": "string",    "at": "string",    "reason": "string"  },  "approvalChannels": [    "kubectl"  ],  "approvalMethod": "slack"}

Deny Access Request

POST
/v1/access-requests/{id}/deny

Customer gate — an authenticated workspace member or administrator other than the requester may reject a queued access request. Actor identity comes from authentication.

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

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/access-requests/string/deny" \  -H "Content-Type: application/json" \  -d '{    "method": "slack"  }'
{  "id": "string",  "requesterKind": "user",  "requesterId": "string",  "requestedExpiresAt": "string",  "deploymentId": "string",  "deployment": {    "id": "string",    "name": "string",    "deploymentGroup": {      "id": "dg_r27ict8c7vcgsumpj90ackf7b",      "name": "prod-us-east-1",      "externalId": "ext_example_01"    }  },  "remediationPlanId": "string",  "agentSessionId": "string",  "title": "string",  "reason": "string",  "commands": [    {      "command": "kubernetes/get-pods",      "summary": "List pods in the ingestion namespace",      "params": {        "pod": "ingester-p4kwm"      },      "tier": "read-only",      "pluginVersion": "string",      "operationContractHash": "string"    }  ],  "operationPattern": "string",  "maxRisk": "read-only",  "debugGrant": {    "tool": "kubectl",    "namespace": "braintrust",    "cloudScope": "123456789012/prod-readonly"  },  "status": "pending-approval",  "approvedUntil": "string",  "createdAt": "string",  "queuedBy": "string",  "queuedAt": "string",  "approvedBy": {    "method": "string",    "actorId": "string",    "at": "string"  },  "deniedBy": {    "actorId": "string",    "at": "string"  },  "revokedBy": {    "actorKind": "user",    "actorId": "string",    "at": "string",    "reason": "string"  },  "approvalChannels": [    "kubectl"  ]}
GET
/v1/access-requests/{id}/coordinates

The customer's kubectl approve command for a queued access request, or null until the operator has materialized the grant CR and reported its coordinates. Used to update the access-plan message after a decision.

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

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

curl -X GET "https://example.com/v1/access-requests/string/coordinates"
{  "status": "pending-approval",  "approvalChannels": [    "kubectl"  ],  "kubectlApprove": "string"}
GET
/v1/access-requests/{id}/activity

The operation commands and debug sessions an access request authorized, with each command's verification outcome. Authorized like getAccessRequest.

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

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/access-requests/string/activity"
{  "operations": [    {      "commandId": "string",      "invocationId": "string",      "command": "string",      "state": "string",      "createdAt": "string",      "dispatchedAt": "string",      "completedAt": "string",      "verification": {        "state": "not-required",        "reason": "string"      }    }  ],  "debugSessions": [    {      "id": "string",      "state": "pending",      "owner": "string",      "createdAt": "string",      "expiresAt": "string"    }  ]}

Revoke Access Request

POST
/v1/access-requests/{id}/revoke

Revoke a pending, queued or customer-approved access request. The principal that created the request, or any workspace member or administrator who can read its project, may revoke it. Commands the grant authorized that have not been dispatched are failed; dispatched commands finish. Linked debug sessions are stopped and refuse their next request. Revoking an already revoked request returns it unchanged.

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

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/access-requests/string/revoke" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "requesterKind": "user",  "requesterId": "string",  "requestedExpiresAt": "string",  "deploymentId": "string",  "deployment": {    "id": "string",    "name": "string",    "deploymentGroup": {      "id": "dg_r27ict8c7vcgsumpj90ackf7b",      "name": "prod-us-east-1",      "externalId": "ext_example_01"    }  },  "remediationPlanId": "string",  "agentSessionId": "string",  "title": "string",  "reason": "string",  "commands": [    {      "command": "kubernetes/get-pods",      "summary": "List pods in the ingestion namespace",      "params": {        "pod": "ingester-p4kwm"      },      "tier": "read-only",      "pluginVersion": "string",      "operationContractHash": "string"    }  ],  "operationPattern": "string",  "maxRisk": "read-only",  "debugGrant": {    "tool": "kubectl",    "namespace": "braintrust",    "cloudScope": "123456789012/prod-readonly"  },  "status": "pending-approval",  "approvedUntil": "string",  "createdAt": "string",  "queuedBy": "string",  "queuedAt": "string",  "approvedBy": {    "method": "string",    "actorId": "string",    "at": "string"  },  "deniedBy": {    "actorId": "string",    "at": "string"  },  "revokedBy": {    "actorKind": "user",    "actorId": "string",    "at": "string",    "reason": "string"  },  "approvalChannels": [    "kubectl"  ]}

Get Access Request

GET
/v1/access-requests/{id}

Get an access request 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

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

curl -X GET "https://example.com/v1/access-requests/string"
{  "id": "string",  "requesterKind": "user",  "requesterId": "string",  "requestedExpiresAt": "string",  "deploymentId": "string",  "deployment": {    "id": "string",    "name": "string",    "deploymentGroup": {      "id": "dg_r27ict8c7vcgsumpj90ackf7b",      "name": "prod-us-east-1",      "externalId": "ext_example_01"    }  },  "remediationPlanId": "string",  "agentSessionId": "string",  "title": "string",  "reason": "string",  "commands": [    {      "command": "kubernetes/get-pods",      "summary": "List pods in the ingestion namespace",      "params": {        "pod": "ingester-p4kwm"      },      "tier": "read-only",      "pluginVersion": "string",      "operationContractHash": "string"    }  ],  "operationPattern": "string",  "maxRisk": "read-only",  "debugGrant": {    "tool": "kubectl",    "namespace": "braintrust",    "cloudScope": "123456789012/prod-readonly"  },  "status": "pending-approval",  "approvedUntil": "string",  "createdAt": "string",  "queuedBy": "string",  "queuedAt": "string",  "approvedBy": {    "method": "string",    "actorId": "string",    "at": "string"  },  "deniedBy": {    "actorId": "string",    "at": "string"  },  "revokedBy": {    "actorKind": "user",    "actorId": "string",    "at": "string",    "reason": "string"  },  "approvalChannels": [    "kubectl"  ]}