Start a workspace run

Bearer PAT authentication; RBAC permission workspaces.use for the caller’s own workspace, workspaces.manage for another member’s. Starts a command in the workspace against the client’s snapshot and answers the run accepted (202) without waiting for it: the pod syncs the snapshot (base fetched from origin with the repository’s credential, the uploaded bundle on top) and starts the command detached. Follow it on the stream. Only a redacted preview of the argv and the names of the forwarded environment variables are stored.

POST /api/v1/org/workspaces/{workspace_id}/runs

Start a workspace run

Python

import requests

url = "https://platform.ankra.app/api/v1/org/workspaces/{workspace_id}/runs"

payload = {
    "agent_id": "<string>",
    "argv": ["<string>"],
    "head_sha": "<string>",
    "snapshot_sha": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

202

{
  "apply": true,
  "argv_preview": "<string>",
  "base_ref": "<string>",
  "base_sha": "<string>",
  "bundle_object_key": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "cwd_prefix": "<string>",
  "env_names": [
    "<string>"
  ],
  "error_message": "<string>",
  "exit_code": 123,
  "finished_at": "2023-11-07T05:31:56Z",
  "head_sha": "<string>",
  "run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "snapshot_sha": "<string>",
  "started": true,
  "state": "accepted",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-ankra-organisation-id · string

PAT organisation override.

Path Parameters

workspace_id · string<uuid> · required

The workspace.

Body

application/json

A command to run in the workspace against the client's snapshot.

agent_id · string · required

The client worktree's id; each gets its own worktree in the pod.

Maximum string length: 128

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

argv · string[] · required

The command, run without a shell.

Required array length: 1 - 1024 elements

head_sha · string · required

The client's HEAD.

snapshot_sha · string · required

The commit of the client's working tree.

apply · boolean

Run a writer: its changes come back as a patch export.

base_ref · string

The client's origin default branch, refs/remotes/origin/<branch>.

base_sha · string

The commit base_ref points at.

bundle_object_key · string | null

The uploaded delta bundle (object_key of the bundles route); omitted when the workspace lacks nothing.

cwd_prefix · string

The client's directory relative to its worktree root.

env · object

Forwarded environment, held to the server allowlist.

Show child attributes

shallow · string[]

The boundary commits of a shallow client clone.

Response

202

application/json

The run, accepted

One command run in a workspace.

apply · boolean · required

argv_preview · string · required

The command line with secret-shaped arguments masked, at most 200 characters.

base_ref · string · required

base_sha · string · required

bundle_object_key · string | null · required

created_at · string<date-time> · required

cwd_prefix · string · required

env_names · string[] · required

The names of the forwarded environment variables, never their values.

error_message · string | null · required

Why the run ended without an exit code, when the platform could tell: a command that ran the workspace's main container out of memory (it was OOMKilled, which ends every run in it) carries a message naming the container's memory limit and pointing at resources.memory in the repository's workspace profile, and a run ended by the kubelet evicting the workspace pod (an emptyDir volume past its size limit, the node short of memory or disk) carries a message saying so and quoting the kubelet's reason. Null for every other run, which says nothing about how it ended.

exit_code · integer | null · required

The command's exit code, or with started false why it never started (197: resend the full history, 75: the sync failed, 78: the workspace profile's setup failed, 130: cancelled first).

finished_at · string<date-time> | null · required

When the run ended; null while it has not.

head_sha · string · required

run_id · string<uuid> · required

snapshot_sha · string · required

started · boolean | null · required

Whether the command itself started; null when the record alone cannot tell (a cancelled or lost run).

state · enum<string> · required

Available options: accepted, running, finished, not_started, cancelled, lost

user_id · string<uuid> · required

workspace_id · string<uuid> · required