Start a workspace run

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)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_id: '<string>',
    argv: ['<string>'],
    head_sha: '<string>',
    snapshot_sha: '<string>'
  })
};

fetch('https://platform.ankra.app/api/v1/org/workspaces/{workspace_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://platform.ankra.app/api/v1/org/workspaces/{workspace_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "argv": [
    "<string>"
  ],
  "head_sha": "<string>",
  "snapshot_sha": "<string>"
}
'

{
  "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>"
  ],
  "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"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "<string>",
  "error_code": "CLUSTER_OFFLINE",
  "retry_after": 123
}

Workspaces

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

org

workspaces

{workspace_id}

runs

Start a workspace run

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)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_id: '<string>',
    argv: ['<string>'],
    head_sha: '<string>',
    snapshot_sha: '<string>'
  })
};

fetch('https://platform.ankra.app/api/v1/org/workspaces/{workspace_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://platform.ankra.app/api/v1/org/workspaces/{workspace_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "argv": [
    "<string>"
  ],
  "head_sha": "<string>",
  "snapshot_sha": "<string>"
}
'

{
  "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>"
  ],
  "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"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "<string>",
  "error_code": "CLUSTER_OFFLINE",
  "retry_after": 123
}

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

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.

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

API reference

Endpoints

Start a workspace run

Authorizations

Headers

Path Parameters

Body

Response