Create an agent run

import requests

url = "https://api.13-215-85-171.sslip.io/v1/agent-deployments/{deployment_id}/runs"

payload = {
    "version_id": "<string>",
    "input": {},
    "envs": {},
    "retain_on_failure": True,
    "retention_seconds": 2
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request POST \
  --url https://api.13-215-85-171.sslip.io/v1/agent-deployments/{deployment_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "version_id": "<string>",
  "input": {},
  "envs": {},
  "retain_on_failure": true,
  "retention_seconds": 2
}
'

{
  "id": "adrun_1234abcd",
  "deployment_id": "<string>",
  "version_id": "<string>",
  "input": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "retain_on_failure": true,
  "retention_seconds": 2,
  "machine_id": "<string>",
  "process_id": 123,
  "exit_code": 123,
  "failure_reason": "<string>",
  "output_manifest": {},
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "idempotency_key": "<string>"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

{
  "error": "Missing or invalid bearer credential",
  "code": "unauthorized",
  "request_id": "req_123"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

POST

agent-deployments

{deployment_id}

runs

Create an agent run

import requests

url = "https://api.13-215-85-171.sslip.io/v1/agent-deployments/{deployment_id}/runs"

payload = {
    "version_id": "<string>",
    "input": {},
    "envs": {},
    "retain_on_failure": True,
    "retention_seconds": 2
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request POST \
  --url https://api.13-215-85-171.sslip.io/v1/agent-deployments/{deployment_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "version_id": "<string>",
  "input": {},
  "envs": {},
  "retain_on_failure": true,
  "retention_seconds": 2
}
'

{
  "id": "adrun_1234abcd",
  "deployment_id": "<string>",
  "version_id": "<string>",
  "input": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "retain_on_failure": true,
  "retention_seconds": 2,
  "machine_id": "<string>",
  "process_id": 123,
  "exit_code": 123,
  "failure_reason": "<string>",
  "output_manifest": {},
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "idempotency_key": "<string>"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

{
  "error": "Missing or invalid bearer credential",
  "code": "unauthorized",
  "request_id": "req_123"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

{
  "error": "<string>",
  "error_detail": {
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "step_index": 123,
    "attempt": 123,
    "max_attempts": 123,
    "cache_subject": "<string>",
    "build_id": "<string>",
    "request_id": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "build_id": "<string>"
}

Authorizations

Authorization

string

header

required

API key passed as Bearer token

Headers

Idempotency-Key

string

required

Reuse the same key to safely retry the same create, reusable snapshot create, fork, upload create/complete, or agent deployment create operation without duplicating work.

Path Parameters

deployment_id

string

required

Agent deployment ID

Body

application/json

version_id

string | null

input

object

Free-form run input supplied at run creation; passed through to the agent verbatim, deliberately open.

envs

object

write-only

Request-only runtime environment variable values. P0 accepts string values only; future secret references are reserved by AgentSecretReference. Values are injected into agent processes and are not stored in deployment config, run, service, or platform event records.

Show child attributes

retain_on_failure

boolean | null

retention_seconds

integer<int64> | null

Required range: x >= 1

Response

Agent run created

string

required

Example:

"adrun_1234abcd"

deployment_id

string

required

version_id

string

required

mode

enum<string>

required

Available options:

job,

service

status

enum<string>

required

Available options:

queued,

starting,

installing,

running,

succeeded,

failed,

cancelled,

timed_out

input

object

required

Free-form run input supplied at run creation; passed through to the agent verbatim, deliberately open.

created_at

string<date-time>

required

updated_at

string<date-time>

required

retain_on_failure

boolean | null

Per-run override for failed job machine retention. Omit to use deployment debug config.

retention_seconds

integer<int64> | null

Retention TTL in seconds when the run is retained. Defaults to 3600 if retention is enabled without an explicit TTL.

Required range: x >= 1

machine_id

string | null

process_id

integer<uint32> | null

exit_code

integer | null

failure_reason

string | null

output_manifest

object | null

Output manifest produced by the agent runtime (typically containing an outputs array). Deliberately open: the manifest shape is owned by the agent, not the control plane.

started_at

string<date-time> | null

completed_at

string<date-time> | null

idempotency_key

string | null

List agent runs Get an agent run

Overview

Endpoints

Create an agent run

Authorizations

Headers

Path Parameters

Body

Response