Operations
List available operations plugins (builtin + custom) for a project, with their operations and risk tiers.
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 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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Filter by project ID or name.
length <= 100Only 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" } ] } } ] } ]}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().
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 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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Filter by project ID or name.
length <= 100Request 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"}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.
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 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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Filter by project ID or name.
length <= 100Request 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 a plugin operation against a deployment. Honors the approval rules the deployment's release declares in operations().
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 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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Filter by project ID or name.
length <= 100Request 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 a project's access requests, newest first.
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 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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Filter by project ID or name.
length <= 100Filter by status.
Filter by deployment ID.
dep_[0-9a-z]{28}$Only requests proposed by this investigation's remediation plan.
Maximum number of items to return per page
1 <= value <= 10020Cursor 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 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).
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 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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Request 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" ]}Engineer gate — approve a pending access request, queuing it for the operator to materialize. Records who queued it.
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
Query Parameters
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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Response 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"}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.
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
Query Parameters
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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Request 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"}Customer gate — an authenticated workspace member or administrator other than the requester may reject a queued access request. Actor identity comes from authentication.
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
Query Parameters
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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Request 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" ]}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.
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
Query Parameters
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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Response Body
application/json
application/json
curl -X GET "https://example.com/v1/access-requests/string/coordinates"{ "status": "pending-approval", "approvalChannels": [ "kubectl" ], "kubectlApprove": "string"}The operation commands and debug sessions an access request authorized, with each command's verification outcome. Authorized like getAccessRequest.
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
Query Parameters
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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Response 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 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.
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
Query Parameters
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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Request 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 an access request by id.
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
Query Parameters
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.
^(?:ws_[0-9a-zA-Z]{24}|(?!ws[-_])[a-z0-9](-?[a-z0-9])*)$4 <= length <= 100Response 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" ]}