2026-10-22
Praxis Automation runs TypeScript scripts and YAML workflows with reusable Actions, triggers and inspectable run results. This is a Praxis-native API. Differences: choose your own namespace without registration, while praxis is read-only; Actions use ns/name at their current revision, while published scripts and workflows use ns/name@version or @tag; drafts can run directly as source without publishing; schedule and webhook triggers require a published target. Start with praxis.automation.runs.create to test source or execute a published target.
Manage actions, publish scripts and workflows, inspect runs, and receive inbound webhooks.
https://api.deepraxis.ai/automation/v1
Use Authorization: Bearer $PRAXIS_API_KEY. Inbound webhooks use the secret URL returned on creation or rotation, without an API Key.
The SDK is not published to npm. Install from local source and run examples with Bun; replace the path with your local SDK directory.
bun add /absolute/path/to/packages/sdk/typescript
bun example.tsExamples target develop. Install jq for curl bodies containing variables. Choose unused names beginning with sample-. Actions, scripts and workflows use the docs-samples namespace; archive them after use and delete triggers.
Discover callable Actions and their ns/name references without executing them. Combine each returned namespace and name as ns/name; Action calls use the current revision and do not accept @version or @tag. Filter by name or description; results include seven-day statistics and revision summaries without implementation source. Archived actions are excluded by default.
GET /automation/v1/actions
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| query: limit | integer | optional; Page size: integer 1–100, default 20. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: q | string | optional; Case-insensitive literal substring of name or description; % and _ are not wildcards. |
| query: namespace | string[] | optional; Return definitions in this namespace, matched in lowercase. Separate multiple values with commas to match any value. minItems: 1 |
| query: scope | "platform" / "own"[] | optional; platform selects platform definitions, own tenant-created definitions; omit for both. Separate multiple values with commas to match any value. minItems: 1 |
| query: archived | boolean | optional; true selects archived entries only, false unarchived only; default false. |
| query: implementation | "code" / "container" / "shell"[] | optional; Filter implementation kind: code, container or shell; omit for all. Separate multiple values with commas to match any value. minItems: 1 |
| query: labels | object | optional; Filter using labels[k]=v; comma-separated values for one key match any, and different keys match together. |
| query: created_at[gte] | string | optional; Inclusive creation-time lower bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
| query: created_at[lte] | string | optional; Inclusive creation-time upper bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
--get \
--data-urlencode "namespace=docs-samples" \
--data-urlencode "limit=1"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.list({
"query": {
"namespace": [
"docs-samples"
],
"limit": 1
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Actions with their current revision summary and 7-day statistics on this page, ordered by created_at descending, then id descending. |
| data[].id | string | required; Action id, prefixed act_; calls normally use namespace and name instead of the id. |
| data[].namespace | string | required; Action namespace; platform actions use praxis, and a bare name resolves to praxis. |
| data[].name | string | required; Action name; together with namespace it identifies the action. Lowercase letters, digits, dot, underscore and hyphen, up to 64 characters. |
| data[].description | string | required; Free-text action description, at most 1000 characters. |
| data[].labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| data[].owner | string | required; Tenant that owns the action, injected by the gateway; treat it as an opaque string. |
| data[].builtin | boolean | required; true for platform-provided actions (namespace praxis); false for user-created actions. |
| data[].stats_7d | object | required; Seven-day statistics; platform actions are isolated by caller tenant and reflect only the current caller, not global platform totals. no additional fields. |
| data[].stats_7d.calls | number | required; Number of calls to the action over the last seven days, aggregated hourly. |
| data[].stats_7d.failures | number | required; Number of those calls that failed over the last seven days. |
| data[].stats_7d.p50_ms | null / number | required; Approximate upper bound of median latency in milliseconds, using power-of-two buckets rounded up (9 ms → 16 ms), with a separate zero bucket; null when no valid latency samples exist. |
| data[].dependents | object | required; Counts of scripts and workflows that reference the action, measured on the latest version plus drafts. no additional fields. |
| data[].dependents.scripts | number | required; Number of scripts that reference this action. |
| data[].dependents.workflows | number | required; Number of workflows that reference this action. |
| data[].archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| data[].created_at | string | required; Creation time (RFC 3339 UTC). |
| data[].updated_at | string | required; Time of the last update (RFC 3339 UTC). |
| data[].current_revision | object | required; Revision summary used in lists: the contract and run location without implementation source. no additional fields. |
| data[].current_revision.id | string | required; Revision id, prefixed actr_. |
| data[].current_revision.implementation | object | required; Action lists return only {kind, host}, without source; action details return the complete implementation. no additional fields. |
| data[].current_revision.implementation.kind | "code" / "container" / "shell" | required; How an action is implemented. code is a source-code implementation (only language=ts is available now); container is an image plus command and is not yet available; shell is a shell script and is not yet available. |
| data[].current_revision.implementation.host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| data[].current_revision.host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| data[].current_revision.input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| data[].current_revision.input_schema.* (variant 5) | object | Recursive JSON value. |
| data[].current_revision.input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].current_revision.output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| data[].current_revision.output_schema.* (variant 5) | object | Recursive JSON value. |
| data[].current_revision.output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].current_revision.created_at | string | required; Time this revision was created (RFC 3339 UTC). |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
"owner": "tnt_3a9759864ccb4e00",
"namespace": "docs-samples",
"name": "sample-action-1791867412840-b05e8a",
"description": "",
"labels": {},
"builtin": false,
"archived_at": null,
"created_at": "2026-10-13T04:57:09.039Z",
"updated_at": "2026-10-13T04:57:09.039Z",
"current_revision": {
"id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
"implementation": {
"kind": "code",
"host": "isolate"
},
"host": "isolate",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"created_at": "2026-10-13T04:57:09.039Z"
},
"stats_7d": {
"calls": 0,
"failures": 0,
"p50_ms": null
},
"dependents": {
"scripts": 0,
"workflows": 0
}
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Create an action definition and its first revision, folding names to lowercase. Duplicate names within the tenant return NAME_TAKEN; the praxis namespace is read-only.
POST /automation/v1/actions
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
no additional fields.
| Field | Type | Description |
|---|---|---|
| namespace | string | required; Choose a namespace without prior registration; praxis is read-only. Folded to lowercase; matches [a-z0-9][a-z0-9.-]{0,63}. pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$" |
| name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9.-]{0,63}. pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$" |
| description | string | optional; Description, at most 1,000 characters. maxLength: 1000 |
| input_schema | object | required; Input JSON Schema; updates may only widen accepted input. |
| input_schema.* (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Output JSON Schema; updates may only narrow output guarantees. |
| output_schema.* (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| errors | object[] | optional; Declared error types and descriptions; existing errors cannot be removed during updates. |
| errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| errors[].code | string | optional; Optional stable error code callers can branch on. |
| errors[].description | string | required; What this error means and when it occurs, written for callers. |
| annotations | object | optional; Boolean read_only and idempotent annotations, both defaulting to false. no additional fields. |
| annotations.read_only | boolean | optional; true declares that the action does not change external state and only reads data. Defaults to false. |
| annotations.idempotent | boolean | optional; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). Defaults to false. |
| timeout_ms | number | optional; Positive integer milliseconds; code defaults to and is capped at 30,000. container/shell are not yet available. |
| implementation | object / object / object | required; Implementation: code uses language=ts and source; container (image, command) and shell (script) are not yet available and return OPERATION_NOT_SUPPORTED on creation or update. |
| implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| implementation (variant 1).source | string | required; Complete TypeScript source of the action. |
| implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available; returns OPERATION_NOT_SUPPORTED). |
| implementation (variant 2).image | string | required; Container image reference. |
| implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available; returns OPERATION_NOT_SUPPORTED). |
| implementation (variant 3).script | string | required; Full text of the shell script to run. |
| labels | object | optional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters. |
| message | string | optional; A message describing this revision. |
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/actions" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"namespace": "docs-samples",
"name": "sample-action",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.create({
"body": {
"namespace": "docs-samples",
"name": "sample-action",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Action id, prefixed act_; calls normally use namespace and name instead of the id. |
| namespace | string | required; Action namespace; platform actions use praxis, and a bare name resolves to praxis. |
| name | string | required; Action name; together with namespace it identifies the action. Lowercase letters, digits, dot, underscore and hyphen, up to 64 characters. |
| description | string | required; Free-text action description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the action, injected by the gateway; treat it as an opaque string. |
| builtin | boolean | required; true for platform-provided actions (namespace praxis); false for user-created actions. |
| current_revision | object | required; One immutable revision of an action: a snapshot of its contract, implementation and run settings. Each update that changes content creates a new revision. no additional fields. |
| current_revision.id | string | required; Revision id, prefixed actr_; used for display and as the revision of a rollback, and cannot be referenced directly by scripts. |
| current_revision.digest | string | required; Content digest of the contract and implementation; an update with identical content does not create a new revision. |
| current_revision.input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.input_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.output_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.errors | object[] | required; Errors the action declares it may raise, each with type, code and description. |
| current_revision.errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| current_revision.errors[].code | string | optional; Optional stable error code callers can branch on. |
| current_revision.errors[].description | string | required; What this error means and when it occurs, written for callers. |
| current_revision.annotations | object | required; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields. |
| current_revision.annotations.read_only | boolean | required; true declares that the action does not change external state and only reads data. |
| current_revision.annotations.idempotent | boolean | required; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). |
| current_revision.timeout_ms | number | required; Timeout of one execution in milliseconds; when not supplied it defaults to 30000 for code and 600000 for container or shell implementations. |
| current_revision.implementation | object / object / object | required; code uses language=ts and source. container and shell are not yet available; creation returns OPERATION_NOT_SUPPORTED. |
| current_revision.implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| current_revision.implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| current_revision.implementation (variant 1).source | string | required; Complete TypeScript source of the action; empty for built-in actions. |
| current_revision.implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available). |
| current_revision.implementation (variant 2).image | string | required; Container image reference. |
| current_revision.implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| current_revision.implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available). |
| current_revision.implementation (variant 3).script | string | required; Full text of the shell script to run. |
| current_revision.host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| current_revision.platform_apis | string[] | required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege). |
| current_revision.created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| current_revision.created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| current_revision.created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| current_revision.message | null / string | required; Note supplied when this revision was created, or null. |
| current_revision.created_at | string | required; Time this revision was created (RFC 3339 UTC). |
| stats_7d | object | required; Seven-day statistics; platform actions are isolated by caller tenant and reflect only the current caller, not global platform totals. no additional fields. |
| stats_7d.calls | number | required; Number of calls to the action over the last seven days, aggregated hourly. |
| stats_7d.failures | number | required; Number of those calls that failed over the last seven days. |
| stats_7d.p50_ms | null / number | required; Approximate upper bound of median latency in milliseconds, using power-of-two buckets rounded up (9 ms → 16 ms), with a separate zero bucket; null when no valid latency samples exist. |
| dependents | object | required; Counts of scripts and workflows that reference the action, measured on the latest version plus drafts. no additional fields. |
| dependents.scripts | number | required; Number of scripts that reference this action. |
| dependents.workflows | number | required; Number of workflows that reference this action. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
"owner": "tnt_3a9759864ccb4e00",
"namespace": "docs-samples",
"name": "sample-action-1791867412840-b05e8a",
"description": "",
"labels": {},
"builtin": false,
"current_revision": {
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"host": "isolate",
"platform_apis": [],
"id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": null,
"created_at": "2026-10-13T04:57:09.039Z"
},
"stats_7d": {
"calls": 0,
"failures": 0,
"p50_ms": null
},
"dependents": {
"scripts": 0,
"workflows": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:09.039Z",
"updated_at": "2026-10-13T04:57:09.039Z"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. NAME_TAKEN: The name is already used by this tenant. |
| 413 | PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read the action and its full current implementation. The response ETag is the current revision ID for conditional updates.
GET /automation/v1/actions/{ns}/{name}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.retrieve({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME")
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| ETag | string | Current resource revision for conditional updates. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Action id, prefixed act_; calls normally use namespace and name instead of the id. |
| namespace | string | required; Action namespace; platform actions use praxis, and a bare name resolves to praxis. |
| name | string | required; Action name; together with namespace it identifies the action. Lowercase letters, digits, dot, underscore and hyphen, up to 64 characters. |
| description | string | required; Free-text action description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the action, injected by the gateway; treat it as an opaque string. |
| builtin | boolean | required; true for platform-provided actions (namespace praxis); false for user-created actions. |
| current_revision | object | required; One immutable revision of an action: a snapshot of its contract, implementation and run settings. Each update that changes content creates a new revision. no additional fields. |
| current_revision.id | string | required; Revision id, prefixed actr_; used for display and as the revision of a rollback, and cannot be referenced directly by scripts. |
| current_revision.digest | string | required; Content digest of the contract and implementation; an update with identical content does not create a new revision. |
| current_revision.input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.input_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.output_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.errors | object[] | required; Errors the action declares it may raise, each with type, code and description. |
| current_revision.errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| current_revision.errors[].code | string | optional; Optional stable error code callers can branch on. |
| current_revision.errors[].description | string | required; What this error means and when it occurs, written for callers. |
| current_revision.annotations | object | required; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields. |
| current_revision.annotations.read_only | boolean | required; true declares that the action does not change external state and only reads data. |
| current_revision.annotations.idempotent | boolean | required; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). |
| current_revision.timeout_ms | number | required; Timeout of one execution in milliseconds; when not supplied it defaults to 30000 for code and 600000 for container or shell implementations. |
| current_revision.implementation | object / object / object | required; code uses language=ts and source. container and shell are not yet available; creation returns OPERATION_NOT_SUPPORTED. |
| current_revision.implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| current_revision.implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| current_revision.implementation (variant 1).source | string | required; Complete TypeScript source of the action; empty for built-in actions. |
| current_revision.implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available). |
| current_revision.implementation (variant 2).image | string | required; Container image reference. |
| current_revision.implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| current_revision.implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available). |
| current_revision.implementation (variant 3).script | string | required; Full text of the shell script to run. |
| current_revision.host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| current_revision.platform_apis | string[] | required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege). |
| current_revision.created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| current_revision.created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| current_revision.created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| current_revision.message | null / string | required; Note supplied when this revision was created, or null. |
| current_revision.created_at | string | required; Time this revision was created (RFC 3339 UTC). |
| stats_7d | object | required; Seven-day statistics; platform actions are isolated by caller tenant and reflect only the current caller, not global platform totals. no additional fields. |
| stats_7d.calls | number | required; Number of calls to the action over the last seven days, aggregated hourly. |
| stats_7d.failures | number | required; Number of those calls that failed over the last seven days. |
| stats_7d.p50_ms | null / number | required; Approximate upper bound of median latency in milliseconds, using power-of-two buckets rounded up (9 ms → 16 ms), with a separate zero bucket; null when no valid latency samples exist. |
| dependents | object | required; Counts of scripts and workflows that reference the action, measured on the latest version plus drafts. no additional fields. |
| dependents.scripts | number | required; Number of scripts that reference this action. |
| dependents.workflows | number | required; Number of workflows that reference this action. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
"owner": "tnt_3a9759864ccb4e00",
"namespace": "docs-samples",
"name": "sample-action-1791867412840-b05e8a",
"description": "",
"labels": {},
"builtin": false,
"archived_at": null,
"created_at": "2026-10-13T04:57:09.039Z",
"updated_at": "2026-10-13T04:57:09.039Z",
"current_revision": {
"id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"host": "isolate",
"platform_apis": [],
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": null,
"created_at": "2026-10-13T04:57:09.039Z"
},
"stats_7d": {
"calls": 0,
"failures": 0,
"p50_ms": null
},
"dependents": {
"scripts": 0,
"workflows": 0
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Update after checking compatibility against the current and five recent revisions. Widening inputs and narrowing outputs are compatible, including length, item count, property count, type (integer/number), and multipleOf (the new input factor divides the old one; the reverse holds for outputs). dry_run=true returns only CompatResult and may omit If-Match; a supplied header is still checked, and * matches any existing representation. Normal updates require If-Match and return ActionDef with ETag; previews return no ETag. Omitted optional fields retain their existing values only for description and labels; when constructing a new revision, errors defaults to [], omitted annotations keys to false, timeout_ms to 30000, and message to null. Incompatible normal updates return 422 SCHEMA_INCOMPATIBLE with issues; unchanged contents retain the existing revision.
PUT /automation/v1/actions/{ns}/{name}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| query: dry_run | boolean | optional; true checks compatibility without persisting and may omit If-Match; omitted or false performs a normal update. |
| header: If-Match | string | optional; Required for normal updates; optional for dry_run=true but still validated when supplied. * matches any existing representation; otherwise supply the current revision ETag. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| description | string | optional; Description, at most 1,000 characters. maxLength: 1000 |
| labels | object | optional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters. |
| input_schema | object | required; Input JSON Schema; updates may only widen accepted input. |
| input_schema.* (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Output JSON Schema; updates may only narrow output guarantees. |
| output_schema.* (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| errors | object[] | optional; Declared error types and descriptions; existing errors cannot be removed during updates. |
| errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| errors[].code | string | optional; Optional stable error code callers can branch on. |
| errors[].description | string | required; What this error means and when it occurs, written for callers. |
| annotations | object | optional; Boolean read_only and idempotent annotations, both defaulting to false. no additional fields. |
| annotations.read_only | boolean | optional; true declares that the action does not change external state and only reads data. Defaults to false. |
| annotations.idempotent | boolean | optional; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). Defaults to false. |
| timeout_ms | number | optional; Positive integer milliseconds; code defaults to and is capped at 30,000. container/shell are not yet available. |
| implementation | object / object / object | required; Implementation: code uses language=ts and source; container (image, command) and shell (script) are not yet available and return OPERATION_NOT_SUPPORTED on creation or update. |
| implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| implementation (variant 1).source | string | required; Complete TypeScript source of the action. |
| implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available; returns OPERATION_NOT_SUPPORTED). |
| implementation (variant 2).image | string | required; Container image reference. |
| implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available; returns OPERATION_NOT_SUPPORTED). |
| implementation (variant 3).script | string | required; Full text of the shell script to run. |
| message | string | optional; A message describing this revision. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
| ETAG | Latest GET response ETag header (preserve quotes) |
: "${ACTION_NAME:?Set ACTION_NAME}"
: "${ETAG:?Set ETAG}"
curl --fail-with-body -X PUT "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "If-Match: ${ETAG}" \
-H "Content-Type: application/json" \
--data '{
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"message": "Sample revision"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.update({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME")
},
"headers": {
"If-Match": env("ETAG")
},
"body": {
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"message": "Sample revision"
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| ETag | string | Current revision returned only for normal updates; absent for dry_run=true. |
application/json
| Field | Type | Description |
|---|---|---|
| (variant 1).id | string | required; Action id, prefixed act_; calls normally use namespace and name instead of the id. |
| (variant 1).namespace | string | required; Action namespace; platform actions use praxis, and a bare name resolves to praxis. |
| (variant 1).name | string | required; Action name; together with namespace it identifies the action. Lowercase letters, digits, dot, underscore and hyphen, up to 64 characters. |
| (variant 1).description | string | required; Free-text action description, at most 1000 characters. |
| (variant 1).labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| (variant 1).owner | string | required; Tenant that owns the action, injected by the gateway; treat it as an opaque string. |
| (variant 1).builtin | boolean | required; true for platform-provided actions (namespace praxis); false for user-created actions. |
| (variant 1).current_revision | object | required; One immutable revision of an action: a snapshot of its contract, implementation and run settings. Each update that changes content creates a new revision. no additional fields. |
| (variant 1).current_revision.id | string | required; Revision id, prefixed actr_; used for display and as the revision of a rollback, and cannot be referenced directly by scripts. |
| (variant 1).current_revision.digest | string | required; Content digest of the contract and implementation; an update with identical content does not create a new revision. |
| (variant 1).current_revision.input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| (variant 1).current_revision.input_schema.* (variant 5) | object | Recursive JSON value. |
| (variant 1).current_revision.input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).current_revision.output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| (variant 1).current_revision.output_schema.* (variant 5) | object | Recursive JSON value. |
| (variant 1).current_revision.output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).current_revision.errors | object[] | required; Errors the action declares it may raise, each with type, code and description. |
| (variant 1).current_revision.errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| (variant 1).current_revision.errors[].code | string | optional; Optional stable error code callers can branch on. |
| (variant 1).current_revision.errors[].description | string | required; What this error means and when it occurs, written for callers. |
| (variant 1).current_revision.annotations | object | required; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields. |
| (variant 1).current_revision.annotations.read_only | boolean | required; true declares that the action does not change external state and only reads data. |
| (variant 1).current_revision.annotations.idempotent | boolean | required; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). |
| (variant 1).current_revision.timeout_ms | number | required; Timeout of one execution in milliseconds; when not supplied it defaults to 30000 for code and 600000 for container or shell implementations. |
| (variant 1).current_revision.implementation | object / object / object | required; code uses language=ts and source. container and shell are not yet available; creation returns OPERATION_NOT_SUPPORTED. |
| (variant 1).current_revision.implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| (variant 1).current_revision.implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| (variant 1).current_revision.implementation (variant 1).source | string | required; Complete TypeScript source of the action; empty for built-in actions. |
| (variant 1).current_revision.implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available). |
| (variant 1).current_revision.implementation (variant 2).image | string | required; Container image reference. |
| (variant 1).current_revision.implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| (variant 1).current_revision.implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available). |
| (variant 1).current_revision.implementation (variant 3).script | string | required; Full text of the shell script to run. |
| (variant 1).current_revision.host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| (variant 1).current_revision.platform_apis | string[] | required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege). |
| (variant 1).current_revision.created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| (variant 1).current_revision.created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| (variant 1).current_revision.created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| (variant 1).current_revision.message | null / string | required; Note supplied when this revision was created, or null. |
| (variant 1).current_revision.created_at | string | required; Time this revision was created (RFC 3339 UTC). |
| (variant 1).stats_7d | object | required; Seven-day statistics; platform actions are isolated by caller tenant and reflect only the current caller, not global platform totals. no additional fields. |
| (variant 1).stats_7d.calls | number | required; Number of calls to the action over the last seven days, aggregated hourly. |
| (variant 1).stats_7d.failures | number | required; Number of those calls that failed over the last seven days. |
| (variant 1).stats_7d.p50_ms | null / number | required; Approximate upper bound of median latency in milliseconds, using power-of-two buckets rounded up (9 ms → 16 ms), with a separate zero bucket; null when no valid latency samples exist. |
| (variant 1).dependents | object | required; Counts of scripts and workflows that reference the action, measured on the latest version plus drafts. no additional fields. |
| (variant 1).dependents.scripts | number | required; Number of scripts that reference this action. |
| (variant 1).dependents.workflows | number | required; Number of workflows that reference this action. |
| (variant 1).archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| (variant 1).created_at | string | required; Creation time (RFC 3339 UTC). |
| (variant 1).updated_at | string | required; Time of the last update (RFC 3339 UTC). |
| (variant 2) (variant 1).compatible | true | required; Always true: the new contract is compatible with the current and five most recent revisions. |
| (variant 2) (variant 2).compatible | false | required; Always false: the new contract is incompatible with earlier revisions in at least one place. |
| (variant 2) (variant 2).issues | object[] | required; Every incompatibility found, each with pointer and reason. |
| (variant 2) (variant 2).issues[].pointer | string | required; JSON Pointer (RFC 6901) to the incompatible location, relative to the action's input_schema or output_schema. |
| (variant 2) (variant 2).issues[].reason | string | required; Why this location is incompatible with earlier revisions (inputs may only widen, outputs may only narrow). |
HTTP 200
{
"id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
"owner": "tnt_3a9759864ccb4e00",
"namespace": "docs-samples",
"name": "sample-action-1791867412840-b05e8a",
"description": "",
"labels": {},
"builtin": false,
"archived_at": null,
"created_at": "2026-10-13T04:57:09.039Z",
"updated_at": "2026-10-13T04:57:12.709Z",
"current_revision": {
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"host": "isolate",
"platform_apis": [],
"id": "actr_00mv67lrt1370820a9daaa4fd3882332e4899a4c9e",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": "Sample revision",
"created_at": "2026-10-13T04:57:12.709Z"
},
"stats_7d": {
"calls": 0,
"failures": 0,
"p50_ms": null
},
"dependents": {
"scripts": 0,
"workflows": 0
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 413 | PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation. |
| 422 | SCHEMA_INCOMPATIBLE: The new action contract is incompatible with previous revisions. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
List revisions newest first with rollback eligibility. Results include the current marker and compatibility issues. Lists omit source by default; only expand=source includes full source, and other values return 400. Detail endpoints retain full source.
GET /automation/v1/actions/{ns}/{name}/revisions
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| query: limit | integer | optional; Page size: integer 1–100, default 20. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: expand | "source" | optional; Only source is accepted; source is omitted by default and other values return 400. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/revisions" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.revisions.list({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Action revisions (implementation source only with expand=source) on this page, ordered by created_at descending, then id descending. |
| data[].current | boolean | required; true when this is the action's current revision. |
| data[].rollback | object | required; Whether rolling back to this revision is possible, judged by the server against the current revision. no additional fields. |
| data[].rollback.allowed | boolean | required; true when rolling back to this revision is allowed; when false, issues explains why. |
| data[].rollback.issues | object[] | required; Incompatibilities a rollback would cause, each with pointer and reason; empty when allowed is true. |
| data[].rollback.issues[].pointer | string | required; JSON Pointer (RFC 6901) to the incompatible location, relative to the action's input_schema or output_schema. |
| data[].rollback.issues[].reason | string | required; Why this location is incompatible with earlier revisions (inputs may only widen, outputs may only narrow). |
| data[].id | string | required; Revision id, prefixed actr_; used for display and as the revision of a rollback, and cannot be referenced directly by scripts. |
| data[].digest | string | required; Content digest of the contract and implementation; an update with identical content does not create a new revision. |
| data[].input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| data[].input_schema.* (variant 5) | object | Recursive JSON value. |
| data[].input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| data[].output_schema.* (variant 5) | object | Recursive JSON value. |
| data[].output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].errors | object[] | required; Errors the action declares it may raise, each with type, code and description. |
| data[].errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| data[].errors[].code | string | optional; Optional stable error code callers can branch on. |
| data[].errors[].description | string | required; What this error means and when it occurs, written for callers. |
| data[].annotations | object | required; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields. |
| data[].annotations.read_only | boolean | required; true declares that the action does not change external state and only reads data. |
| data[].annotations.idempotent | boolean | required; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). |
| data[].timeout_ms | number | required; Timeout of one execution in milliseconds; when not supplied it defaults to 30000 for code and 600000 for container or shell implementations. |
| data[].implementation | object / object / object / object | required; Implementation information: the full implementation or only its kind; lists omit source, so use expand=source or read a single revision. |
| data[].implementation (variant 1) (variant 1).kind | "code" | required; Always code: implemented by source code. |
| data[].implementation (variant 1) (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| data[].implementation (variant 1) (variant 1).source | string | required; Complete TypeScript source of the action; empty for built-in actions. |
| data[].implementation (variant 1) (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available). |
| data[].implementation (variant 1) (variant 2).image | string | required; Container image reference. |
| data[].implementation (variant 1) (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| data[].implementation (variant 1) (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available). |
| data[].implementation (variant 1) (variant 3).script | string | required; Full text of the shell script to run. |
| data[].implementation (variant 2).kind | "code" / "container" / "shell" | required; How an action is implemented. code is a source-code implementation (only language=ts is available now); container is an image plus command and is not yet available; shell is a shell script and is not yet available. |
| data[].host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| data[].platform_apis | string[] | required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege). |
| data[].created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| data[].created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[].message | null / string | required; Note supplied when this revision was created, or null. |
| data[].created_at | string | required; Time this revision was created (RFC 3339 UTC). |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "actr_00mv67lrt1370820a9daaa4fd3882332e4899a4c9e",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"host": "isolate",
"platform_apis": [],
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": "Sample revision",
"created_at": "2026-10-13T04:57:12.709Z",
"current": true,
"rollback": {
"allowed": true,
"issues": []
},
"implementation": {
"kind": "code"
}
},
{
"id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"host": "isolate",
"platform_apis": [],
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": null,
"created_at": "2026-10-13T04:57:09.039Z",
"current": false,
"rollback": {
"allowed": true,
"issues": []
},
"implementation": {
"kind": "code"
}
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read a specific revision with its full implementation and rollback compatibility result. A missing revision returns VERSION_NOT_FOUND. Details always return full source.
GET /automation/v1/actions/{ns}/{name}/revisions/{revision}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: revision | string | required; Action revision ID (actr_); the query parameter filters invocation records. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
| REVISION_ID | Existing function revision id |
: "${ACTION_NAME:?Set ACTION_NAME}"
: "${REVISION_ID:?Set REVISION_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/revisions/${REVISION_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.revisions.retrieve({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME"),
"revision": env("REVISION_ID")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| current | boolean | required; true when this is the action's current revision. |
| rollback | object | required; Whether rolling back to this revision is possible, judged by the server against the current revision. no additional fields. |
| rollback.allowed | boolean | required; true when rolling back to this revision is allowed; when false, issues explains why. |
| rollback.issues | object[] | required; Incompatibilities a rollback would cause, each with pointer and reason; empty when allowed is true. |
| rollback.issues[].pointer | string | required; JSON Pointer (RFC 6901) to the incompatible location, relative to the action's input_schema or output_schema. |
| rollback.issues[].reason | string | required; Why this location is incompatible with earlier revisions (inputs may only widen, outputs may only narrow). |
| id | string | required; Revision id, prefixed actr_; used for display and as the revision of a rollback, and cannot be referenced directly by scripts. |
| digest | string | required; Content digest of the contract and implementation; an update with identical content does not create a new revision. |
| input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| input_schema.* (variant 5) | object | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| output_schema.* (variant 5) | object | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| errors | object[] | required; Errors the action declares it may raise, each with type, code and description. |
| errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| errors[].code | string | optional; Optional stable error code callers can branch on. |
| errors[].description | string | required; What this error means and when it occurs, written for callers. |
| annotations | object | required; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields. |
| annotations.read_only | boolean | required; true declares that the action does not change external state and only reads data. |
| annotations.idempotent | boolean | required; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). |
| timeout_ms | number | required; Timeout of one execution in milliseconds; when not supplied it defaults to 30000 for code and 600000 for container or shell implementations. |
| implementation | object / object / object | required; code uses language=ts and source. container and shell are not yet available; creation returns OPERATION_NOT_SUPPORTED. |
| implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| implementation (variant 1).source | string | required; Complete TypeScript source of the action; empty for built-in actions. |
| implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available). |
| implementation (variant 2).image | string | required; Container image reference. |
| implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available). |
| implementation (variant 3).script | string | required; Full text of the shell script to run. |
| host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| platform_apis | string[] | required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege). |
| created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| message | null / string | required; Note supplied when this revision was created, or null. |
| created_at | string | required; Time this revision was created (RFC 3339 UTC). |
HTTP 200
{
"id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"host": "isolate",
"platform_apis": [],
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": null,
"created_at": "2026-10-13T04:57:09.039Z",
"current": false,
"rollback": {
"allowed": true,
"issues": []
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Create a compatible new revision from historical contents. Compatibility is checked against the current and five recent historical revisions. The current pointer does not revert to the old ID. Optional If-Match accepts the current revision or *; * matches any existing representation.
POST /automation/v1/actions/{ns}/{name}/rollback
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| header: If-Match | string | optional; Optional current revision or *; checked when supplied, with * matching any existing representation. |
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
no additional fields.
| Field | Type | Description |
|---|---|---|
| revision | string | required; Historical revision ID (actr_) to copy into a new revision. |
| message | string | optional; A message describing this revision. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
| REVISION_ID | Existing function revision id |
: "${ACTION_NAME:?Set ACTION_NAME}"
: "${REVISION_ID:?Set REVISION_ID}"
BODY=$(jq -n --arg REVISION_ID "$REVISION_ID" '{
"revision": $REVISION_ID
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/rollback" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data "$BODY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.rollback({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME")
},
"body": {
"revision": env("REVISION_ID")
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
| ETag | string | Current revision ID after rollback. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Action id, prefixed act_; calls normally use namespace and name instead of the id. |
| namespace | string | required; Action namespace; platform actions use praxis, and a bare name resolves to praxis. |
| name | string | required; Action name; together with namespace it identifies the action. Lowercase letters, digits, dot, underscore and hyphen, up to 64 characters. |
| description | string | required; Free-text action description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the action, injected by the gateway; treat it as an opaque string. |
| builtin | boolean | required; true for platform-provided actions (namespace praxis); false for user-created actions. |
| current_revision | object | required; One immutable revision of an action: a snapshot of its contract, implementation and run settings. Each update that changes content creates a new revision. no additional fields. |
| current_revision.id | string | required; Revision id, prefixed actr_; used for display and as the revision of a rollback, and cannot be referenced directly by scripts. |
| current_revision.digest | string | required; Content digest of the contract and implementation; an update with identical content does not create a new revision. |
| current_revision.input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.input_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.output_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.errors | object[] | required; Errors the action declares it may raise, each with type, code and description. |
| current_revision.errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| current_revision.errors[].code | string | optional; Optional stable error code callers can branch on. |
| current_revision.errors[].description | string | required; What this error means and when it occurs, written for callers. |
| current_revision.annotations | object | required; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields. |
| current_revision.annotations.read_only | boolean | required; true declares that the action does not change external state and only reads data. |
| current_revision.annotations.idempotent | boolean | required; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). |
| current_revision.timeout_ms | number | required; Timeout of one execution in milliseconds; when not supplied it defaults to 30000 for code and 600000 for container or shell implementations. |
| current_revision.implementation | object / object / object | required; code uses language=ts and source. container and shell are not yet available; creation returns OPERATION_NOT_SUPPORTED. |
| current_revision.implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| current_revision.implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| current_revision.implementation (variant 1).source | string | required; Complete TypeScript source of the action; empty for built-in actions. |
| current_revision.implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available). |
| current_revision.implementation (variant 2).image | string | required; Container image reference. |
| current_revision.implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| current_revision.implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available). |
| current_revision.implementation (variant 3).script | string | required; Full text of the shell script to run. |
| current_revision.host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| current_revision.platform_apis | string[] | required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege). |
| current_revision.created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| current_revision.created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| current_revision.created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| current_revision.message | null / string | required; Note supplied when this revision was created, or null. |
| current_revision.created_at | string | required; Time this revision was created (RFC 3339 UTC). |
| stats_7d | object | required; Seven-day statistics; platform actions are isolated by caller tenant and reflect only the current caller, not global platform totals. no additional fields. |
| stats_7d.calls | number | required; Number of calls to the action over the last seven days, aggregated hourly. |
| stats_7d.failures | number | required; Number of those calls that failed over the last seven days. |
| stats_7d.p50_ms | null / number | required; Approximate upper bound of median latency in milliseconds, using power-of-two buckets rounded up (9 ms → 16 ms), with a separate zero bucket; null when no valid latency samples exist. |
| dependents | object | required; Counts of scripts and workflows that reference the action, measured on the latest version plus drafts. no additional fields. |
| dependents.scripts | number | required; Number of scripts that reference this action. |
| dependents.workflows | number | required; Number of workflows that reference this action. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
"owner": "tnt_3a9759864ccb4e00",
"namespace": "docs-samples",
"name": "sample-action-1791867412840-b05e8a",
"description": "",
"labels": {},
"builtin": false,
"archived_at": null,
"created_at": "2026-10-13T04:57:09.039Z",
"updated_at": "2026-10-13T04:57:15.629Z",
"current_revision": {
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"host": "isolate",
"platform_apis": [],
"id": "actr_00mv67lu25f7f28dd81a924c698b9d2557056a7b62",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": "回滚到 actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
"created_at": "2026-10-13T04:57:15.629Z"
},
"stats_7d": {
"calls": 0,
"failures": 0,
"p50_ms": null
},
"dependents": {
"scripts": 0,
"workflows": 0
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 413 | PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. SCHEMA_INCOMPATIBLE: The new action contract is incompatible with previous revisions. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
List this action’s invocations, filtering by status, revision, calling definition and time. Results identify the run and call site.
GET /automation/v1/actions/{ns}/{name}/invocations
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| query: limit | integer | optional; Page size: integer 1–100, default 20. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: status | "running" / "completed" / "faulted" / "cancelled"[] | optional; Comma-separated statuses: running, completed, faulted, cancelled; omit for all. |
| query: revision | string | optional; Action revision ID (actr_); the query parameter filters invocation records. |
| query: caller | string | optional; Exact calling script or workflow name, in ns/name format. |
| query: run_kind | "script" / "workflow" | optional; Calling run kind: script or workflow. |
| query: created_at[gte] | string | optional; Inclusive creation-time lower bound in RFC 3339 with timezone, e.g. 2026-10-01T00:00:00Z. format: "date-time" |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/invocations" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.invocations.list({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Invocation records of the action on this page, ordered by created_at descending, then id descending. |
| data[].id | string | required; Invocation identity without a separate inv_ prefix: scripts use run_id:seq (run ID and call sequence); workflows use the task execution key plus attempt. Treat it as opaque. |
| data[].created_at | string | required; Time the invocation record was created (RFC 3339 UTC). |
| data[].started_at | null / string | required; Time the action started executing, or null if it has not started. |
| data[].ended_at | null / string | required; Time the action finished, or null while it is still running. |
| data[].status | "running" / "completed" / "faulted" / "cancelled" | required; Call status. running means still executing; completed means it returned normally; faulted means it failed and error explains why; cancelled means it was stopped because the run was cancelled. |
| data[].duration_ms | null / number | required; Execution time in milliseconds, or null until it finishes. |
| data[].revision | string | required; Id (actr_) of the action revision that executed. |
| data[].run | object | required; The run that made this invocation: {id, kind, definition, number, source_digest}. no additional fields. |
| data[].run.id | string | required; Id (run_) of the run that made the call; use it to read that run. |
| data[].run.kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[].run.definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs. |
| data[].run.definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| data[].run.definition (variant 2).name | string | required; Name of the script or workflow. |
| data[].run.number | null / number | required; Sequence number of the run within its script or workflow; null for ad-hoc runs. |
| data[].run.source_digest | null / string | required; Digest of the source of an ad-hoc run; null for runs started from a published definition. |
| data[].site | object / object | required; Where the invocation happened: a call in a script (kind=call with seq) or a workflow step (kind=task with reference and iteration). |
| data[].site (variant 1).kind | "call" | required; Always call: made by a call in a script. |
| data[].site (variant 1).seq | number | required; Sequence number of the call within the script run; matches Call.seq. |
| data[].site (variant 2).kind | "task" | required; Always task: made by a workflow step. |
| data[].site (variant 2).reference | string | required; JSON Pointer of the step inside the workflow document; matches Task.reference. |
| data[].site (variant 2).iteration | number[] | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| data[].error | null / object | required; {code, message} of the failure, or null when it succeeded or is still running. |
| data[].error (variant 2).code | string | required; Error code, such as a code the action declares or a platform error code. |
| data[].error (variant 2).message | string | required; Human-readable error message. |
| data[].result_preview | null / string | required; Single-line preview of the returned value, truncated on the server; null if unfinished or failed. |
| data[].request_id | string / null | required; Downstream response X-Request-Id, or null when absent; use it to trace failed invocations. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
List orchestrations referencing this action. The search covers scripts and workflows in their drafts or latest versions.
GET /automation/v1/actions/{ns}/{name}/dependents
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| query: limit | integer | optional; Page size: integer 1–100, default 20. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/dependents" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.dependents.list({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Referencing scripts and workflows (measured on the latest version plus drafts) on this page, ordered by created_at descending, then id descending. |
| data[].kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[].namespace | string | required; Namespace of the referencing script or workflow. |
| data[].name | string | required; Name of the referencing script or workflow. |
| data[].at | string | required; Reference location: draft or latest version number; draft means the draft, otherwise this is the definition’s latest published version. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Archive the action while retaining its name and history, hiding it from the default list. The response includes dependents_count.
POST /automation/v1/actions/{ns}/{name}/archive
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
no additional fields. object
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/archive" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.archive({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Action id, prefixed act_; calls normally use namespace and name instead of the id. |
| namespace | string | required; Action namespace; platform actions use praxis, and a bare name resolves to praxis. |
| name | string | required; Action name; together with namespace it identifies the action. Lowercase letters, digits, dot, underscore and hyphen, up to 64 characters. |
| description | string | required; Free-text action description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the action, injected by the gateway; treat it as an opaque string. |
| builtin | boolean | required; true for platform-provided actions (namespace praxis); false for user-created actions. |
| current_revision | object | required; One immutable revision of an action: a snapshot of its contract, implementation and run settings. Each update that changes content creates a new revision. no additional fields. |
| current_revision.id | string | required; Revision id, prefixed actr_; used for display and as the revision of a rollback, and cannot be referenced directly by scripts. |
| current_revision.digest | string | required; Content digest of the contract and implementation; an update with identical content does not create a new revision. |
| current_revision.input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.input_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.output_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.errors | object[] | required; Errors the action declares it may raise, each with type, code and description. |
| current_revision.errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| current_revision.errors[].code | string | optional; Optional stable error code callers can branch on. |
| current_revision.errors[].description | string | required; What this error means and when it occurs, written for callers. |
| current_revision.annotations | object | required; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields. |
| current_revision.annotations.read_only | boolean | required; true declares that the action does not change external state and only reads data. |
| current_revision.annotations.idempotent | boolean | required; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). |
| current_revision.timeout_ms | number | required; Timeout of one execution in milliseconds; when not supplied it defaults to 30000 for code and 600000 for container or shell implementations. |
| current_revision.implementation | object / object / object | required; code uses language=ts and source. container and shell are not yet available; creation returns OPERATION_NOT_SUPPORTED. |
| current_revision.implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| current_revision.implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| current_revision.implementation (variant 1).source | string | required; Complete TypeScript source of the action; empty for built-in actions. |
| current_revision.implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available). |
| current_revision.implementation (variant 2).image | string | required; Container image reference. |
| current_revision.implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| current_revision.implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available). |
| current_revision.implementation (variant 3).script | string | required; Full text of the shell script to run. |
| current_revision.host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| current_revision.platform_apis | string[] | required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege). |
| current_revision.created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| current_revision.created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| current_revision.created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| current_revision.message | null / string | required; Note supplied when this revision was created, or null. |
| current_revision.created_at | string | required; Time this revision was created (RFC 3339 UTC). |
| stats_7d | object | required; Seven-day statistics; platform actions are isolated by caller tenant and reflect only the current caller, not global platform totals. no additional fields. |
| stats_7d.calls | number | required; Number of calls to the action over the last seven days, aggregated hourly. |
| stats_7d.failures | number | required; Number of those calls that failed over the last seven days. |
| stats_7d.p50_ms | null / number | required; Approximate upper bound of median latency in milliseconds, using power-of-two buckets rounded up (9 ms → 16 ms), with a separate zero bucket; null when no valid latency samples exist. |
| dependents | object | required; Counts of scripts and workflows that reference the action, measured on the latest version plus drafts. no additional fields. |
| dependents.scripts | number | required; Number of scripts that reference this action. |
| dependents.workflows | number | required; Number of workflows that reference this action. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
| dependents_count | integer | required; Number of scripts and workflows still referencing the action at archive time (dependents.scripts plus dependents.workflows). minimum: 0 |
HTTP 200
{
"id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
"owner": "tnt_3a9759864ccb4e00",
"namespace": "docs-samples",
"name": "sample-action-1791867412840-b05e8a",
"description": "",
"labels": {},
"builtin": false,
"archived_at": "2026-10-13T04:57:17.830Z",
"created_at": "2026-10-13T04:57:09.039Z",
"updated_at": "2026-10-13T04:57:17.830Z",
"current_revision": {
"id": "actr_00mv67lu25f7f28dd81a924c698b9d2557056a7b62",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"host": "isolate",
"platform_apis": [],
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": "回滚到 actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
"created_at": "2026-10-13T04:57:15.629Z"
},
"stats_7d": {
"calls": 0,
"failures": 0,
"p50_ms": null
},
"dependents": {
"scripts": 0,
"workflows": 0
},
"dependents_count": 0
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Restore an archived action to the default list. Its current revision is preserved.
POST /automation/v1/actions/{ns}/{name}/restore
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
no additional fields. object
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| ACTION_NAME | name returned by creating an action |
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/restore" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.actions.restore({
"path": {
"ns": "docs-samples",
"name": env("ACTION_NAME")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Action id, prefixed act_; calls normally use namespace and name instead of the id. |
| namespace | string | required; Action namespace; platform actions use praxis, and a bare name resolves to praxis. |
| name | string | required; Action name; together with namespace it identifies the action. Lowercase letters, digits, dot, underscore and hyphen, up to 64 characters. |
| description | string | required; Free-text action description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the action, injected by the gateway; treat it as an opaque string. |
| builtin | boolean | required; true for platform-provided actions (namespace praxis); false for user-created actions. |
| current_revision | object | required; One immutable revision of an action: a snapshot of its contract, implementation and run settings. Each update that changes content creates a new revision. no additional fields. |
| current_revision.id | string | required; Revision id, prefixed actr_; used for display and as the revision of a rollback, and cannot be referenced directly by scripts. |
| current_revision.digest | string | required; Content digest of the contract and implementation; an update with identical content does not create a new revision. |
| current_revision.input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.input_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.output_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| current_revision.output_schema.* (variant 5) | object | Recursive JSON value. |
| current_revision.output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| current_revision.errors | object[] | required; Errors the action declares it may raise, each with type, code and description. |
| current_revision.errors[].type | string | required; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime. |
| current_revision.errors[].code | string | optional; Optional stable error code callers can branch on. |
| current_revision.errors[].description | string | required; What this error means and when it occurs, written for callers. |
| current_revision.annotations | object | required; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields. |
| current_revision.annotations.read_only | boolean | required; true declares that the action does not change external state and only reads data. |
| current_revision.annotations.idempotent | boolean | required; true declares that repeating a call with the same input has the same effect as calling once; retries of such a action reuse one idempotency key (run_id plus step path, without the attempt number). |
| current_revision.timeout_ms | number | required; Timeout of one execution in milliseconds; when not supplied it defaults to 30000 for code and 600000 for container or shell implementations. |
| current_revision.implementation | object / object / object | required; code uses language=ts and source. container and shell are not yet available; creation returns OPERATION_NOT_SUPPORTED. |
| current_revision.implementation (variant 1).kind | "code" | required; Always code: implemented by source code. |
| current_revision.implementation (variant 1).language | "ts" | required; Source language; only ts (TypeScript) is supported now. |
| current_revision.implementation (variant 1).source | string | required; Complete TypeScript source of the action; empty for built-in actions. |
| current_revision.implementation (variant 2).kind | "container" | required; Always container: implemented as a container image (not yet available). |
| current_revision.implementation (variant 2).image | string | required; Container image reference. |
| current_revision.implementation (variant 2).command | string[] | required; Command and arguments to execute in the container. |
| current_revision.implementation (variant 3).kind | "shell" | required; Always shell: implemented as a shell script (not yet available). |
| current_revision.implementation (variant 3).script | string | required; Full text of the shell script to run. |
| current_revision.host | "builtin" / "isolate" / "sandbox" | required; Where an action runs, computed at publication. builtin is a platform-provided action; isolate runs user code in an isolated Worker isolate; sandbox runs in a sandbox (container and shell implementations). |
| current_revision.platform_apis | string[] | required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege). |
| current_revision.created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| current_revision.created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| current_revision.created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| current_revision.message | null / string | required; Note supplied when this revision was created, or null. |
| current_revision.created_at | string | required; Time this revision was created (RFC 3339 UTC). |
| stats_7d | object | required; Seven-day statistics; platform actions are isolated by caller tenant and reflect only the current caller, not global platform totals. no additional fields. |
| stats_7d.calls | number | required; Number of calls to the action over the last seven days, aggregated hourly. |
| stats_7d.failures | number | required; Number of those calls that failed over the last seven days. |
| stats_7d.p50_ms | null / number | required; Approximate upper bound of median latency in milliseconds, using power-of-two buckets rounded up (9 ms → 16 ms), with a separate zero bucket; null when no valid latency samples exist. |
| dependents | object | required; Counts of scripts and workflows that reference the action, measured on the latest version plus drafts. no additional fields. |
| dependents.scripts | number | required; Number of scripts that reference this action. |
| dependents.workflows | number | required; Number of workflows that reference this action. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
"owner": "tnt_3a9759864ccb4e00",
"namespace": "docs-samples",
"name": "sample-action-1791867412840-b05e8a",
"description": "",
"labels": {},
"builtin": false,
"archived_at": null,
"created_at": "2026-10-13T04:57:09.039Z",
"updated_at": "2026-10-13T04:57:18.573Z",
"current_revision": {
"id": "actr_00mv67lu25f7f28dd81a924c698b9d2557056a7b62",
"digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
],
"additionalProperties": false
},
"errors": [],
"annotations": {
"read_only": false,
"idempotent": false
},
"timeout_ms": 30000,
"implementation": {
"kind": "code",
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
},
"host": "isolate",
"platform_apis": [],
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"message": "回滚到 actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
"created_at": "2026-10-13T04:57:15.629Z"
},
"stats_7d": {
"calls": 0,
"failures": 0,
"p50_ms": null
},
"dependents": {
"scripts": 0,
"workflows": 0
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
List visible script summaries, latest versions, tags and seven-day statistics. Archived entries are excluded by default.
GET /automation/v1/scripts
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| query: limit | integer | optional; Page size: integer 1–100, default 25. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: q | string | optional; Case-insensitive literal substring of name or description; % and _ are not wildcards. |
| query: namespace | string[] | optional; Return definitions in this namespace, matched in lowercase. Separate multiple values with commas to match any value. minItems: 1 |
| query: scope | "platform" / "own"[] | optional; platform selects platform definitions, own tenant-created definitions; omit for both. Separate multiple values with commas to match any value. minItems: 1 |
| query: archived | boolean | optional; true selects archived entries only, false unarchived only; default false. |
| query: labels | object | optional; Filter using labels[k]=v; comma-separated values for one key match any, and different keys match together. |
| query: created_at[gte] | string | optional; Inclusive creation-time lower bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
| query: created_at[lte] | string | optional; Inclusive creation-time upper bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
--get \
--data-urlencode "namespace=docs-samples" \
--data-urlencode "limit=1"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.list({
"query": {
"namespace": [
"docs-samples"
],
"limit": 1
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Script summaries on this page, ordered by created_at descending, then id descending. |
| data[].id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| data[].kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[].namespace | string | required; Namespace; references take the form namespace/name@version. |
| data[].name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| data[].description | string | required; Free-text description, at most 1000 characters. |
| data[].labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| data[].owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| data[].latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| data[].latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| data[].latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| data[].dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| data[].draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| data[].latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| data[].latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| data[].latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| data[].latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| data[].latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| data[].latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| data[].latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| data[].latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| data[].latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| data[].latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| data[].latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| data[].latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| data[].latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| data[].latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| data[].latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| data[].latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| data[].latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| data[].latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| data[].latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| data[].stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| data[].stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| data[].stats_7d.failures | number | required; How many of those runs ended faulted. |
| data[].archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| data[].created_at | string | required; Creation time (RFC 3339 UTC). |
| data[].updated_at | string | required; Time of the last update (RFC 3339 UTC). |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
"owner": "tnt_3a9759864ccb4e00",
"kind": "script",
"namespace": "docs-samples",
"name": "sample-scripts-1791867412840-b05e8a",
"description": "",
"labels": {},
"latest_version": null,
"dist_tags": {},
"draft_changed": true,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:19.277Z",
"updated_at": "2026-10-13T04:57:19.277Z"
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Save a TypeScript script as an editable draft for later reuse; this does not publish or start a run. Choose your own namespace without registering it first; praxis is read-only. Scripts and workflows share names within the tenant; a duplicate returns NAME_TAKEN. The draft is a source string with a default-exported function, for example export default async (input: {name: string}) => ({greeting: "Hello, " + input.name});. To test it, pass that source and language=ts to praxis.automation.runs.create without publishing. To publish later, use the returned draft.revision as expected_draft_revision.
POST /automation/v1/scripts
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
no additional fields.
| Field | Type | Description |
|---|---|---|
| namespace | string | required; Choose a namespace without prior registration; praxis is read-only. Folded to lowercase; matches [a-z0-9][a-z0-9.-]{0,63}. pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$" |
| name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9.-]{0,63}. pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$" |
| description | string | optional; Description, at most 1,000 characters. maxLength: 1000 |
| draft | string | optional; Editable source: TypeScript for scripts, YAML for workflows. Defaults to an empty string on creation. |
| labels | object | optional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters. |
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"namespace": "docs-samples",
"name": "sample-scripts",
"draft": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.create({
"body": {
"namespace": "docs-samples",
"name": "sample-scripts",
"draft": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| Field | Type | Description |
|---|---|---|
| draft | object | required; The editable draft of a script or workflow; publishing takes the draft or a run's source. no additional fields. |
| draft.source | string | required; Draft source: TypeScript for scripts, YAML for workflows. |
| draft.revision | string | required; Draft revision tag (ETag); send it as expected_draft_revision when publishing or as If-Match when updating the draft; a mismatch returns 412. |
| draft.updated_at | string | required; Time the draft was last changed (RFC 3339 UTC). |
| draft.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| draft.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| draft.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
"owner": "tnt_3a9759864ccb4e00",
"kind": "script",
"namespace": "docs-samples",
"name": "sample-scripts-1791867412840-b05e8a",
"description": "",
"labels": {},
"latest_version": null,
"dist_tags": {},
"draft_changed": true,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:19.277Z",
"updated_at": "2026-10-13T04:57:19.277Z",
"draft": {
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
"revision": "draft_00mv67lwvh333793ba7d9e47cb89b5fd8b43fb4fa3",
"updated_at": "2026-10-13T04:57:19.277Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. NAME_TAKEN: The name is already used by this tenant. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read script details and draft source. The ETag is the draft revision to use in If-Match for updates.
GET /automation/v1/scripts/{ns}/{name}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.retrieve({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME")
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| ETag | string | Current resource revision for conditional updates. |
application/json
| Field | Type | Description |
|---|---|---|
| draft | object | required; The editable draft of a script or workflow; publishing takes the draft or a run's source. no additional fields. |
| draft.source | string | required; Draft source: TypeScript for scripts, YAML for workflows. |
| draft.revision | string | required; Draft revision tag (ETag); send it as expected_draft_revision when publishing or as If-Match when updating the draft; a mismatch returns 412. |
| draft.updated_at | string | required; Time the draft was last changed (RFC 3339 UTC). |
| draft.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| draft.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| draft.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
"owner": "tnt_3a9759864ccb4e00",
"kind": "script",
"namespace": "docs-samples",
"name": "sample-scripts-1791867412840-b05e8a",
"description": "",
"labels": {},
"latest_version": null,
"dist_tags": {},
"draft_changed": true,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:19.277Z",
"updated_at": "2026-10-13T04:57:19.277Z",
"draft": {
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
"revision": "draft_00mv67lwvh333793ba7d9e47cb89b5fd8b43fb4fa3",
"updated_at": "2026-10-13T04:57:19.277Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Update description, labels or draft with the current draft revision in If-Match. Even metadata-only updates create a new draft revision.
PATCH /automation/v1/scripts/{ns}/{name}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| header: If-Match | string | required; Current resource ETag. The value of the object's draft.revision or etag field can be used directly: the bare value, the quoted form and the weak form W/"…" are all accepted (RFC 7232 weak comparison). Omission returns 400 and a revision mismatch returns 412. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| description | string | optional; Description, at most 1,000 characters. maxLength: 1000 |
| labels | object | optional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters. |
| draft | string | optional; Editable source: TypeScript for scripts, YAML for workflows. Defaults to an empty string on creation. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
| ETAG | Latest GET response ETag header (preserve quotes) |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
: "${ETAG:?Set ETAG}"
curl --fail-with-body -X PATCH "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "If-Match: ${ETAG}" \
-H "Content-Type: application/json" \
--data '{
"description": "Sample definition",
"draft": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.update({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME")
},
"headers": {
"If-Match": env("ETAG")
},
"body": {
"description": "Sample definition",
"draft": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| draft | object | required; The editable draft of a script or workflow; publishing takes the draft or a run's source. no additional fields. |
| draft.source | string | required; Draft source: TypeScript for scripts, YAML for workflows. |
| draft.revision | string | required; Draft revision tag (ETag); send it as expected_draft_revision when publishing or as If-Match when updating the draft; a mismatch returns 412. |
| draft.updated_at | string | required; Time the draft was last changed (RFC 3339 UTC). |
| draft.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| draft.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| draft.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
"owner": "tnt_3a9759864ccb4e00",
"kind": "script",
"namespace": "docs-samples",
"name": "sample-scripts-1791867412840-b05e8a",
"description": "Sample definition",
"labels": {},
"latest_version": null,
"dist_tags": {},
"draft_changed": true,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:19.277Z",
"updated_at": "2026-10-13T04:57:21.691Z",
"draft": {
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
"revision": "draft_00mv67lwvh333793ba7d9e47cb89b5fd8b43fb4fa3",
"updated_at": "2026-10-13T04:57:19.277Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Keep the name, versions and draft while archiving. The default list hides it and new target resolution and run requests reject the archived target.
POST /automation/v1/scripts/{ns}/{name}/archive
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
no additional fields. object
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/archive" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.archive({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
"owner": "tnt_3a9759864ccb4e00",
"kind": "script",
"namespace": "docs-samples",
"name": "sample-scripts-1791867412840-b05e8a",
"description": "Sample definition",
"labels": {},
"latest_version": {
"version": "1.0.0",
"published_at": "2026-10-13T04:57:22.398Z"
},
"dist_tags": {
"latest": "1.0.0"
},
"draft_changed": false,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": "2026-10-13T04:57:27.639Z",
"created_at": "2026-10-13T04:57:19.277Z",
"updated_at": "2026-10-13T04:57:27.639Z"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Restore an archived definition with its versions and tags. The name is retained.
POST /automation/v1/scripts/{ns}/{name}/restore
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
no additional fields. object
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/restore" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.restore({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
"owner": "tnt_3a9759864ccb4e00",
"kind": "script",
"namespace": "docs-samples",
"name": "sample-scripts-1791867412840-b05e8a",
"description": "Sample definition",
"labels": {},
"latest_version": {
"version": "1.0.0",
"published_at": "2026-10-13T04:57:22.398Z"
},
"dist_tags": {
"latest": "1.0.0"
},
"draft_changed": false,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:19.277Z",
"updated_at": "2026-10-13T04:57:28.559Z"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Publish a saved definition from its draft or an ad hoc run as a reusable version for named runs or triggers, validating the definition and locking dependencies. To test unpublished code, use praxis.automation.runs.create with source and language instead. Use draft.revision from create or retrieve as expected_draft_revision. The draft must match expected_draft_revision; an ad hoc run requires from_run and expected_source_sha256. The same version and contents return the existing version; different contents return VERSION_EXISTS, prereleases require an explicit tag (not latest, URL-safe characters only, not a version or range; violations return TAG_REQUIRED or TAG_INVALID with the complete rules in hint), and invalid definitions return DEFINITION_INVALID. Stable releases automatically advance latest only above the highest existing stable version; workflows becoming latest synchronize their declared schedule. Publishing removes +build metadata from the version number.
POST /automation/v1/scripts/{ns}/{name}/versions
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
| Field | Type | Description |
|---|---|---|
| (variant 1).version | string | required; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. |
| (variant 1).expected_draft_revision | string | required; Draft revision to publish, matching the current draft; alternative to publishing from_run. |
| (variant 1).tag | string | optional; Distribution tag. A prerelease (such as 1.3.0-beta.1) requires a tag and it cannot be latest; a tag may only use URL-safe characters (letters, digits and - _ . ! ~ * ' ( )), no spaces or / ? # and no leading or trailing whitespace; it cannot be a version or a version range (such as 1.2.3, ^1, 1.x, *); any other name such as beta, next or debug is allowed. Violations return TAG_INVALID or TAG_REQUIRED with the complete rules in hint. |
| (variant 2).version | string | required; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. |
| (variant 2).from_run | string | required; Ad hoc run ID providing the source snapshot; published-target runs currently have no snapshot usable by this endpoint. Requires expected_source_sha256 and excludes expected_draft_revision. |
| (variant 2).expected_source_sha256 | string | required; SHA-256 digest of the run source, matching the snapshot. |
| (variant 2).tag | string | optional; Distribution tag. A prerelease (such as 1.3.0-beta.1) requires a tag and it cannot be latest; a tag may only use URL-safe characters (letters, digits and - _ . ! ~ * ' ( )), no spaces or / ? # and no leading or trailing whitespace; it cannot be a version or a version range (such as 1.2.3, ^1, 1.x, *); any other name such as beta, next or debug is allowed. Violations return TAG_INVALID or TAG_REQUIRED with the complete rules in hint. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
| DRAFT_REVISION | Current draft.revision |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
: "${DRAFT_REVISION:?Set DRAFT_REVISION}"
BODY=$(jq -n --arg DRAFT_REVISION "$DRAFT_REVISION" '{
"version": "1.0.0",
"expected_draft_revision": $DRAFT_REVISION
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/versions" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data "$BODY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.versions.publish({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME")
},
"body": {
"version": "1.0.0",
"expected_draft_revision": env("DRAFT_REVISION")
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Version id, prefixed scv_ for scripts and wfv_ for workflows. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| version | string | required; Version number (semver, with +build metadata removed). |
| digest | string | required; Content digest of the source and contract. |
| source | string | required; Full source of this version. Version lists omit it unless expand=source is given. |
| input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| input_schema.* (variant 5) | object | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| output_schema.* (variant 5) | object | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| references | object[] | required; Actions, platform APIs, scripts and workflows this version depends on. Script and workflow dependencies are locked to exact versions at publication. |
| references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| outline | null / object[] | required; Step outline of a workflow as OutlineNode entries generated statically by the parser; null for scripts. |
| outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| outline (variant 2)[].children[] | object | Recursive JSON value. |
| sdk_version | null / string | required; SDK version used when publishing a script; null for workflows. |
| published_at | string | required; Publication time (RFC 3339 UTC). |
| published_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| published_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| published_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| deprecated | null / string | required; Deprecation message, or null when not deprecated. A deprecated version still runs, but resolving a range or tag prefers versions that are not deprecated. |
| deprecated_at | null / string | required; Time the version was deprecated (RFC 3339 UTC), or null. |
| deprecated_by | null / object | required; Principal that deprecated the version, or null. |
| deprecated_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| deprecated_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
"kind": "script",
"version": "1.0.0",
"digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
]
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
]
},
"references": [],
"outline": null,
"sdk_version": "0.1.0",
"published_at": "2026-10-13T04:57:22.398Z",
"published_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"deprecated": null,
"deprecated_at": null,
"deprecated_by": null,
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. TAG_REQUIRED: A prerelease version requires an explicit publication tag (for example beta, not latest); the response hint lists the complete rules. TAG_INVALID: The tag is invalid: a prerelease cannot use latest; a tag may only use URL-safe characters (no spaces or / ? #); it cannot be a version or range; latest cannot be deleted. The response hint lists the complete rules. DEFINITION_INVALID: The source failed definition validation. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. VERSION_EXISTS: The version already exists with different source content. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. DEFINITION_IDENTITY_MISMATCH: The source identity or runtime language does not match the publication target. NO_MATCHING_VERSION: No published version matches the requested tag, version, or range. CYCLE_DETECTED: Publication would create a dependency cycle (A depends on B and B depends on A); the detail names the cycle path. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Page through immutable schemas and locked dependencies in descending semantic-version order. Lists omit source by default; only expand=source includes full source, and other values return 400. Detail endpoints retain full source.
GET /automation/v1/scripts/{ns}/{name}/versions
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| query: limit | integer | optional; Page size: integer 1–100, default 25. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: expand | "source" | optional; Only source is accepted; source is omitted by default and other values return 400. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/versions" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.versions.list({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Script versions (source only with expand=source) on this page, ordered by semver descending. |
| data[].id | string | required; Version id, prefixed scv_ for scripts and wfv_ for workflows. |
| data[].kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[].version | string | required; Version number (semver, with +build metadata removed). |
| data[].digest | string | required; Content digest of the source and contract. |
| data[].source | string | optional; Full source of this version. Version lists omit it unless expand=source is given. |
| data[].input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| data[].input_schema.* (variant 5) | object | Recursive JSON value. |
| data[].input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].output_schema | object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| data[].output_schema.* (variant 5) | object | Recursive JSON value. |
| data[].output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].references | object[] | required; Actions, platform APIs, scripts and workflows this version depends on. Script and workflow dependencies are locked to exact versions at publication. |
| data[].references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| data[].references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| data[].references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| data[].references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| data[].outline | null / object[] | required; Step outline of a workflow as OutlineNode entries generated statically by the parser; null for scripts. |
| data[].outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| data[].outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| data[].outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| data[].outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| data[].outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| data[].outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| data[].outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| data[].outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| data[].outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| data[].outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| data[].outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| data[].outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| data[].outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| data[].outline (variant 2)[].children[] | object | Recursive JSON value. |
| data[].sdk_version | null / string | required; SDK version used when publishing a script; null for workflows. |
| data[].published_at | string | required; Publication time (RFC 3339 UTC). |
| data[].published_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| data[].published_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].published_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[].deprecated | null / string | required; Deprecation message, or null when not deprecated. A deprecated version still runs, but resolving a range or tag prefers versions that are not deprecated. |
| data[].deprecated_at | null / string | required; Time the version was deprecated (RFC 3339 UTC), or null. |
| data[].deprecated_by | null / object | required; Principal that deprecated the version, or null. |
| data[].deprecated_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].deprecated_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
"kind": "script",
"version": "1.0.0",
"digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
]
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
]
},
"references": [],
"outline": null,
"sdk_version": "0.1.0",
"published_at": "2026-10-13T04:57:22.398Z",
"published_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"deprecated": null,
"deprecated_at": null,
"deprecated_by": null
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read source, input/output schemas and deprecation details for an exact version. Missing versions return VERSION_NOT_FOUND. Details always return full source. version accepts an exact version or dist-tag; a range returns 400 with a hint to use /resolve.
GET /automation/v1/scripts/{ns}/{name}/versions/{version}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: version | string | required; Exact version or dist-tag; ranges are rejected with 400 and a hint. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/versions/1.0.0" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.versions.retrieve({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME"),
"version": "1.0.0"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Version id, prefixed scv_ for scripts and wfv_ for workflows. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| version | string | required; Version number (semver, with +build metadata removed). |
| digest | string | required; Content digest of the source and contract. |
| source | string | required; Full source of this version. Version lists omit it unless expand=source is given. |
| input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| input_schema.* (variant 5) | object | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| output_schema.* (variant 5) | object | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| references | object[] | required; Actions, platform APIs, scripts and workflows this version depends on. Script and workflow dependencies are locked to exact versions at publication. |
| references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| outline | null / object[] | required; Step outline of a workflow as OutlineNode entries generated statically by the parser; null for scripts. |
| outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| outline (variant 2)[].children[] | object | Recursive JSON value. |
| sdk_version | null / string | required; SDK version used when publishing a script; null for workflows. |
| published_at | string | required; Publication time (RFC 3339 UTC). |
| published_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| published_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| published_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| deprecated | null / string | required; Deprecation message, or null when not deprecated. A deprecated version still runs, but resolving a range or tag prefers versions that are not deprecated. |
| deprecated_at | null / string | required; Time the version was deprecated (RFC 3339 UTC), or null. |
| deprecated_by | null / object | required; Principal that deprecated the version, or null. |
| deprecated_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| deprecated_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
"kind": "script",
"version": "1.0.0",
"digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
]
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
]
},
"references": [],
"outline": null,
"sdk_version": "0.1.0",
"published_at": "2026-10-13T04:57:22.398Z",
"published_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"deprecated": null,
"deprecated_at": null,
"deprecated_by": null,
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Record a deprecation message; an empty message removes deprecation without changing the version source.
POST /automation/v1/scripts/{ns}/{name}/versions/{version}/deprecate
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: version | string | required; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| message | string | required; Deprecation message; an empty string removes deprecation. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/versions/1.0.0/deprecate" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"message": ""
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.versions.deprecate({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME"),
"version": "1.0.0"
},
"body": {
"message": ""
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Version id, prefixed scv_ for scripts and wfv_ for workflows. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| version | string | required; Version number (semver, with +build metadata removed). |
| digest | string | required; Content digest of the source and contract. |
| source | string | required; Full source of this version. Version lists omit it unless expand=source is given. |
| input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| input_schema.* (variant 5) | object | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| output_schema.* (variant 5) | object | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| references | object[] | required; Actions, platform APIs, scripts and workflows this version depends on. Script and workflow dependencies are locked to exact versions at publication. |
| references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| outline | null / object[] | required; Step outline of a workflow as OutlineNode entries generated statically by the parser; null for scripts. |
| outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| outline (variant 2)[].children[] | object | Recursive JSON value. |
| sdk_version | null / string | required; SDK version used when publishing a script; null for workflows. |
| published_at | string | required; Publication time (RFC 3339 UTC). |
| published_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| published_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| published_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| deprecated | null / string | required; Deprecation message, or null when not deprecated. A deprecated version still runs, but resolving a range or tag prefers versions that are not deprecated. |
| deprecated_at | null / string | required; Time the version was deprecated (RFC 3339 UTC), or null. |
| deprecated_by | null / object | required; Principal that deprecated the version, or null. |
| deprecated_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| deprecated_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
"kind": "script",
"version": "1.0.0",
"digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
]
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
]
},
"references": [],
"outline": null,
"sdk_version": "0.1.0",
"published_at": "2026-10-13T04:57:22.398Z",
"published_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"deprecated": null,
"deprecated_at": null,
"deprecated_by": null,
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read the exact version for each distribution tag. Results include the update time and updater.
GET /automation/v1/scripts/{ns}/{name}/dist-tags
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/dist-tags" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.distTags.list({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| .*.version | string | required; Exact version the tag currently points to. |
| .*.updated_at | string | required; Time the tag was last moved (RFC 3339 UTC). |
| .*.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| .*.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| .*.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"latest": {
"version": "1.0.0",
"updated_at": "2026-10-13T04:57:22.398Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Point a distribution tag at an existing exact version; tags cannot be versions or version ranges. Moving latest can roll back a release and synchronizes workflow schedules.
PUT /automation/v1/scripts/{ns}/{name}/dist-tags/{tag}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: tag | string | required; Distribution tag. A prerelease (such as 1.3.0-beta.1) requires a tag and it cannot be latest; a tag may only use URL-safe characters (letters, digits and - _ . ! ~ * ' ( )), no spaces or / ? # and no leading or trailing whitespace; it cannot be a version or a version range (such as 1.2.3, ^1, 1.x, *); any other name such as beta, next or debug is allowed. Violations return TAG_INVALID or TAG_REQUIRED with the complete rules in hint. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| version | string | required; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X PUT "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/dist-tags/sample" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"version": "1.0.0"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.distTags.set({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME"),
"tag": "sample"
},
"body": {
"version": "1.0.0"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| .*.version | string | required; Exact version the tag currently points to. |
| .*.updated_at | string | required; Time the tag was last moved (RFC 3339 UTC). |
| .*.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| .*.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| .*.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"latest": {
"version": "1.0.0",
"updated_at": "2026-10-13T04:57:22.398Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
},
"sample": {
"version": "1.0.0",
"updated_at": "2026-10-13T04:57:26.232Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. TAG_INVALID: The tag is invalid: a prerelease cannot use latest; a tag may only use URL-safe characters (no spaces or / ? #); it cannot be a version or range; latest cannot be deleted. The response hint lists the complete rules. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Delete a distribution tag while retaining versions. latest cannot be deleted, versions and ranges are invalid tags, and deleting an absent valid tag is repeatable.
DELETE /automation/v1/scripts/{ns}/{name}/dist-tags/{tag}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: tag | string | required; Distribution tag. A prerelease (such as 1.3.0-beta.1) requires a tag and it cannot be latest; a tag may only use URL-safe characters (letters, digits and - _ . ! ~ * ' ( )), no spaces or / ? # and no leading or trailing whitespace; it cannot be a version or a version range (such as 1.2.3, ^1, 1.x, *); any other name such as beta, next or debug is allowed. Violations return TAG_INVALID or TAG_REQUIRED with the complete rules in hint. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| SCRIPT_NAME | name returned by creating a script |
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X DELETE "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/dist-tags/sample" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.scripts.distTags.delete({
"path": {
"ns": "docs-samples",
"name": env("SCRIPT_NAME"),
"tag": "sample"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| .*.version | string | required; Exact version the tag currently points to. |
| .*.updated_at | string | required; Time the tag was last moved (RFC 3339 UTC). |
| .*.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| .*.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| .*.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"latest": {
"version": "1.0.0",
"updated_at": "2026-10-13T04:57:22.398Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. TAG_INVALID: The tag is invalid: a prerelease cannot use latest; a tag may only use URL-safe characters (no spaces or / ? #); it cannot be a version or range; latest cannot be deleted. The response hint lists the complete rules. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
List visible workflow summaries, latest versions, tags and seven-day statistics. Archived entries are excluded by default.
GET /automation/v1/workflows
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| query: limit | integer | optional; Page size: integer 1–100, default 25. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: q | string | optional; Case-insensitive literal substring of name or description; % and _ are not wildcards. |
| query: namespace | string[] | optional; Return definitions in this namespace, matched in lowercase. Separate multiple values with commas to match any value. minItems: 1 |
| query: scope | "platform" / "own"[] | optional; platform selects platform definitions, own tenant-created definitions; omit for both. Separate multiple values with commas to match any value. minItems: 1 |
| query: archived | boolean | optional; true selects archived entries only, false unarchived only; default false. |
| query: labels | object | optional; Filter using labels[k]=v; comma-separated values for one key match any, and different keys match together. |
| query: created_at[gte] | string | optional; Inclusive creation-time lower bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
| query: created_at[lte] | string | optional; Inclusive creation-time upper bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
--get \
--data-urlencode "namespace=docs-samples" \
--data-urlencode "limit=1"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.list({
"query": {
"namespace": [
"docs-samples"
],
"limit": 1
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Workflow summaries on this page, ordered by created_at descending, then id descending. |
| data[].id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| data[].kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[].namespace | string | required; Namespace; references take the form namespace/name@version. |
| data[].name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| data[].description | string | required; Free-text description, at most 1000 characters. |
| data[].labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| data[].owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| data[].latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| data[].latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| data[].latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| data[].dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| data[].draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| data[].latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| data[].latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| data[].latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| data[].latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| data[].latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| data[].latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| data[].latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| data[].latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| data[].latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| data[].latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| data[].latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| data[].latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| data[].latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| data[].latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| data[].latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| data[].latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| data[].latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| data[].latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| data[].latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| data[].stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| data[].stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| data[].stats_7d.failures | number | required; How many of those runs ended faulted. |
| data[].archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| data[].created_at | string | required; Creation time (RFC 3339 UTC). |
| data[].updated_at | string | required; Time of the last update (RFC 3339 UTC). |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
"owner": "tnt_3a9759864ccb4e00",
"kind": "workflow",
"namespace": "docs-samples",
"name": "sample-workflows-1791867412840-b05e8a",
"description": "",
"labels": {},
"latest_version": null,
"dist_tags": {},
"draft_changed": true,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:29.206Z",
"updated_at": "2026-10-13T04:57:29.206Z"
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Save a YAML workflow as an editable draft without publishing or starting a run. Choose your own namespace without registering it first; praxis is read-only. To test the draft, send its source and language=yaml to praxis.automation.runs.create. Scripts and workflows share names within the tenant; a duplicate returns NAME_TAKEN. run.workflow accepts ns/name@range or {namespace, name, version, input}; run.script uses the same reference shape as a platform extension. Object namespace, name and version are required; version accepts an exact version, dist-tag or range, locked at publication. Object input defaults to {} and supports expressions; string references retain task-level with. run.await defaults to true and returns the child output. With false, the child uses detach and the task immediately returns {run_id}; parent cancellation does not cascade. Inline script.code returns DEFINITION_INVALID with a detail asking you to save a script and reference it first. raise.error retains its type URI, status, title and detail in the run error.
POST /automation/v1/workflows
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
no additional fields.
| Field | Type | Description |
|---|---|---|
| namespace | string | required; Choose a namespace without prior registration; praxis is read-only. Folded to lowercase; matches [a-z0-9][a-z0-9.-]{0,63}. pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$" |
| name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9.-]{0,63}. pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$" |
| description | string | optional; Description, at most 1,000 characters. maxLength: 1000 |
| draft | string | optional; Editable source: TypeScript for scripts, YAML for workflows. Defaults to an empty string on creation. |
| labels | object | optional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters. |
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"namespace": "docs-samples",
"name": "sample-workflows",
"draft": "document:\n dsl: '\''1.0.3'\''\n namespace: docs-samples\n name: sample-workflows\n version: '\''1.0.0'\''\ndo:\n - answer:\n set:\n answer: 42\n"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.create({
"body": {
"namespace": "docs-samples",
"name": "sample-workflows",
"draft": "document:\n dsl: '1.0.3'\n namespace: docs-samples\n name: sample-workflows\n version: '1.0.0'\ndo:\n - answer:\n set:\n answer: 42\n"
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| Field | Type | Description |
|---|---|---|
| draft | object | required; The editable draft of a script or workflow; publishing takes the draft or a run's source. no additional fields. |
| draft.source | string | required; Draft source: TypeScript for scripts, YAML for workflows. |
| draft.revision | string | required; Draft revision tag (ETag); send it as expected_draft_revision when publishing or as If-Match when updating the draft; a mismatch returns 412. |
| draft.updated_at | string | required; Time the draft was last changed (RFC 3339 UTC). |
| draft.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| draft.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| draft.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
"owner": "tnt_3a9759864ccb4e00",
"kind": "workflow",
"namespace": "docs-samples",
"name": "sample-workflows-1791867412840-b05e8a",
"description": "",
"labels": {},
"latest_version": null,
"dist_tags": {},
"draft_changed": true,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:29.206Z",
"updated_at": "2026-10-13T04:57:29.206Z",
"draft": {
"source": "document:\n dsl: '1.0.3'\n namespace: docs-samples\n name: sample-workflows-1791867412840-b05e8a\n version: '1.0.0'\ndo:\n - answer:\n set:\n answer: 42\n",
"revision": "draft_00mv67m4ja0e38625d463646e3a526bb774bf453ee",
"updated_at": "2026-10-13T04:57:29.206Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. NAME_TAKEN: The name is already used by this tenant. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read workflow details and draft source. The ETag is the draft revision to use in If-Match for updates.
GET /automation/v1/workflows/{ns}/{name}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.retrieve({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME")
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| ETag | string | Current resource revision for conditional updates. |
application/json
| Field | Type | Description |
|---|---|---|
| draft | object | required; The editable draft of a script or workflow; publishing takes the draft or a run's source. no additional fields. |
| draft.source | string | required; Draft source: TypeScript for scripts, YAML for workflows. |
| draft.revision | string | required; Draft revision tag (ETag); send it as expected_draft_revision when publishing or as If-Match when updating the draft; a mismatch returns 412. |
| draft.updated_at | string | required; Time the draft was last changed (RFC 3339 UTC). |
| draft.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| draft.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| draft.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
"owner": "tnt_3a9759864ccb4e00",
"kind": "workflow",
"namespace": "docs-samples",
"name": "sample-workflows-1791867412840-b05e8a",
"description": "",
"labels": {},
"latest_version": null,
"dist_tags": {},
"draft_changed": true,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:29.206Z",
"updated_at": "2026-10-13T04:57:29.206Z",
"draft": {
"source": "document:\n dsl: '1.0.3'\n namespace: docs-samples\n name: sample-workflows-1791867412840-b05e8a\n version: '1.0.0'\ndo:\n - answer:\n set:\n answer: 42\n",
"revision": "draft_00mv67m4ja0e38625d463646e3a526bb774bf453ee",
"updated_at": "2026-10-13T04:57:29.206Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Update description, labels or draft with the current draft revision in If-Match. Even metadata-only updates create a new draft revision.
PATCH /automation/v1/workflows/{ns}/{name}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| header: If-Match | string | required; Current resource ETag. The value of the object's draft.revision or etag field can be used directly: the bare value, the quoted form and the weak form W/"…" are all accepted (RFC 7232 weak comparison). Omission returns 400 and a revision mismatch returns 412. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| description | string | optional; Description, at most 1,000 characters. maxLength: 1000 |
| labels | object | optional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters. |
| draft | string | optional; Editable source: TypeScript for scripts, YAML for workflows. Defaults to an empty string on creation. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
| ETAG | Latest GET response ETag header (preserve quotes) |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
: "${ETAG:?Set ETAG}"
curl --fail-with-body -X PATCH "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "If-Match: ${ETAG}" \
-H "Content-Type: application/json" \
--data '{
"description": "Sample definition",
"draft": "document:\n dsl: '\''1.0.3'\''\n namespace: docs-samples\n name: sample-workflows-1791867412840-b05e8a\n version: '\''1.0.0'\''\ndo:\n - answer:\n set:\n answer: 42\n"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.update({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME")
},
"headers": {
"If-Match": env("ETAG")
},
"body": {
"description": "Sample definition",
"draft": "document:\n dsl: '1.0.3'\n namespace: docs-samples\n name: sample-workflows-1791867412840-b05e8a\n version: '1.0.0'\ndo:\n - answer:\n set:\n answer: 42\n"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| draft | object | required; The editable draft of a script or workflow; publishing takes the draft or a run's source. no additional fields. |
| draft.source | string | required; Draft source: TypeScript for scripts, YAML for workflows. |
| draft.revision | string | required; Draft revision tag (ETag); send it as expected_draft_revision when publishing or as If-Match when updating the draft; a mismatch returns 412. |
| draft.updated_at | string | required; Time the draft was last changed (RFC 3339 UTC). |
| draft.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| draft.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| draft.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
"owner": "tnt_3a9759864ccb4e00",
"kind": "workflow",
"namespace": "docs-samples",
"name": "sample-workflows-1791867412840-b05e8a",
"description": "Sample definition",
"labels": {},
"latest_version": null,
"dist_tags": {},
"draft_changed": true,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:29.206Z",
"updated_at": "2026-10-13T04:57:31.570Z",
"draft": {
"source": "document:\n dsl: '1.0.3'\n namespace: docs-samples\n name: sample-workflows-1791867412840-b05e8a\n version: '1.0.0'\ndo:\n - answer:\n set:\n answer: 42\n",
"revision": "draft_00mv67m4ja0e38625d463646e3a526bb774bf453ee",
"updated_at": "2026-10-13T04:57:29.206Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Keep the name, versions and draft while archiving. The default list hides it and new target resolution and run requests reject the archived target.
POST /automation/v1/workflows/{ns}/{name}/archive
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
no additional fields. object
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/archive" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.archive({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
"owner": "tnt_3a9759864ccb4e00",
"kind": "workflow",
"namespace": "docs-samples",
"name": "sample-workflows-1791867412840-b05e8a",
"description": "Sample definition",
"labels": {},
"latest_version": {
"version": "1.0.0",
"published_at": "2026-10-13T04:57:32.297Z"
},
"dist_tags": {
"latest": "1.0.0"
},
"draft_changed": false,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": "2026-10-13T04:57:37.671Z",
"created_at": "2026-10-13T04:57:29.206Z",
"updated_at": "2026-10-13T04:57:37.671Z"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Restore an archived definition with its versions and tags. The name is retained.
POST /automation/v1/workflows/{ns}/{name}/restore
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
no additional fields. object
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/restore" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.restore({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Definition id, prefixed scr_ for scripts and wf_ for workflows; calls normally use namespace and name. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace; references take the form namespace/name@version. |
| name | string | required; Name; with namespace it is unique within the tenant, and scripts and workflows share one namespace (duplicates return 409 NAME_TAKEN). |
| description | string | required; Free-text description, at most 1000 characters. |
| labels | object | required; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis. |
| owner | string | required; Tenant that owns the definition, injected by the gateway; treat it as an opaque string. |
| latest_version | null / object | required; The published version the latest tag points to, as {version, published_at}; null if nothing is published. |
| latest_version (variant 2).version | string | required; Version number (semver) of the latest published version. |
| latest_version (variant 2).published_at | string | required; Time that version was published (RFC 3339 UTC). |
| dist_tags | object | required; Map from dist-tag to the exact version it points to, for example latest to 1.2.0; ns/name@tag resolves through it. |
| draft_changed | boolean | required; true when the draft content (digest) differs from the latest version, meaning there are unpublished changes. |
| latest_run | null / object | required; Summary of the most recent run of this definition, or null if it has never run. |
| latest_run (variant 2).id | string | required; Run id (run_ prefix); pass it to runs.retrieve. |
| latest_run (variant 2).number | null / number | required; Increasing sequence number of the run within its script or workflow. |
| latest_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed; completed finished successfully. |
| latest_run (variant 2).created_at | string | required; Time the run was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait | null / object | required; The wait point currently open, or null when the run is not waiting. |
| latest_run (variant 2).current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| latest_run (variant 2).current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| latest_run (variant 2).current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| latest_run (variant 2).current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| latest_run (variant 2).current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| latest_run (variant 2).current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| latest_run (variant 2).current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| latest_run (variant 2).current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| latest_run (variant 2).current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| latest_run (variant 2).current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| stats_7d | object | required; Run statistics for the last seven days, bucketed by the day each run ended and updated when runs finish. no additional fields. |
| stats_7d.runs | number | required; Number of runs that ended in the last seven days, in any terminal status. |
| stats_7d.failures | number | required; How many of those runs ended faulted. |
| archived_at | null / string | required; Archive time, or null while not archived. An archived name stays reserved and cannot be reused. |
| created_at | string | required; Creation time (RFC 3339 UTC). |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). |
HTTP 200
{
"id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
"owner": "tnt_3a9759864ccb4e00",
"kind": "workflow",
"namespace": "docs-samples",
"name": "sample-workflows-1791867412840-b05e8a",
"description": "Sample definition",
"labels": {},
"latest_version": {
"version": "1.0.0",
"published_at": "2026-10-13T04:57:32.297Z"
},
"dist_tags": {
"latest": "1.0.0"
},
"draft_changed": false,
"latest_run": null,
"stats_7d": {
"runs": 0,
"failures": 0
},
"archived_at": null,
"created_at": "2026-10-13T04:57:29.206Z",
"updated_at": "2026-10-13T04:57:38.354Z"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Publish a saved definition from its draft or an ad hoc run as a reusable version for named runs or triggers, validating the definition and locking dependencies. To test unpublished code, use praxis.automation.runs.create with source and language instead. Use draft.revision from create or retrieve as expected_draft_revision. The draft must match expected_draft_revision; an ad hoc run requires from_run and expected_source_sha256. The same version and contents return the existing version; different contents return VERSION_EXISTS, prereleases require an explicit tag (not latest, URL-safe characters only, not a version or range; violations return TAG_REQUIRED or TAG_INVALID with the complete rules in hint), and invalid definitions return DEFINITION_INVALID. Stable releases automatically advance latest only above the highest existing stable version; workflows becoming latest synchronize their declared schedule. String and object run.workflow/run.script references share version resolution and dependency locking. Publishing removes +build metadata from the version number.
POST /automation/v1/workflows/{ns}/{name}/versions
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
| Field | Type | Description |
|---|---|---|
| (variant 1).version | string | required; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. |
| (variant 1).expected_draft_revision | string | required; Draft revision to publish, matching the current draft; alternative to publishing from_run. |
| (variant 1).tag | string | optional; Distribution tag. A prerelease (such as 1.3.0-beta.1) requires a tag and it cannot be latest; a tag may only use URL-safe characters (letters, digits and - _ . ! ~ * ' ( )), no spaces or / ? # and no leading or trailing whitespace; it cannot be a version or a version range (such as 1.2.3, ^1, 1.x, *); any other name such as beta, next or debug is allowed. Violations return TAG_INVALID or TAG_REQUIRED with the complete rules in hint. |
| (variant 2).version | string | required; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. |
| (variant 2).from_run | string | required; Ad hoc run ID providing the source snapshot; published-target runs currently have no snapshot usable by this endpoint. Requires expected_source_sha256 and excludes expected_draft_revision. |
| (variant 2).expected_source_sha256 | string | required; SHA-256 digest of the run source, matching the snapshot. |
| (variant 2).tag | string | optional; Distribution tag. A prerelease (such as 1.3.0-beta.1) requires a tag and it cannot be latest; a tag may only use URL-safe characters (letters, digits and - _ . ! ~ * ' ( )), no spaces or / ? # and no leading or trailing whitespace; it cannot be a version or a version range (such as 1.2.3, ^1, 1.x, *); any other name such as beta, next or debug is allowed. Violations return TAG_INVALID or TAG_REQUIRED with the complete rules in hint. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
| DRAFT_REVISION | Current draft.revision |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
: "${DRAFT_REVISION:?Set DRAFT_REVISION}"
BODY=$(jq -n --arg DRAFT_REVISION "$DRAFT_REVISION" '{
"version": "1.0.0",
"expected_draft_revision": $DRAFT_REVISION
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/versions" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data "$BODY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.versions.publish({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME")
},
"body": {
"version": "1.0.0",
"expected_draft_revision": env("DRAFT_REVISION")
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Version id, prefixed scv_ for scripts and wfv_ for workflows. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| version | string | required; Version number (semver, with +build metadata removed). |
| digest | string | required; Content digest of the source and contract. |
| source | string | required; Full source of this version. Version lists omit it unless expand=source is given. |
| input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| input_schema.* (variant 5) | object | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| output_schema.* (variant 5) | object | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| references | object[] | required; Actions, platform APIs, scripts and workflows this version depends on. Script and workflow dependencies are locked to exact versions at publication. |
| references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| outline | null / object[] | required; Step outline of a workflow as OutlineNode entries generated statically by the parser; null for scripts. |
| outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| outline (variant 2)[].children[] | object | Recursive JSON value. |
| sdk_version | null / string | required; SDK version used when publishing a script; null for workflows. |
| published_at | string | required; Publication time (RFC 3339 UTC). |
| published_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| published_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| published_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| deprecated | null / string | required; Deprecation message, or null when not deprecated. A deprecated version still runs, but resolving a range or tag prefers versions that are not deprecated. |
| deprecated_at | null / string | required; Time the version was deprecated (RFC 3339 UTC), or null. |
| deprecated_by | null / object | required; Principal that deprecated the version, or null. |
| deprecated_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| deprecated_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"id": "wfv_00mv67m6x5409408c354944fa8a960d207eb33c297",
"kind": "workflow",
"version": "1.0.0",
"digest": "ea7352d51087eca0113ee82230848ce1506fd97d27aad4c7b1911e5c4ef9b5fb",
"input_schema": {},
"output_schema": {},
"references": [],
"outline": [
{
"name": "answer",
"reference": "/do/0/answer",
"kind": "set"
}
],
"sdk_version": null,
"published_at": "2026-10-13T04:57:32.297Z",
"published_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"deprecated": null,
"deprecated_at": null,
"deprecated_by": null,
"source": "document:\n dsl: '1.0.3'\n namespace: docs-samples\n name: sample-workflows-1791867412840-b05e8a\n version: '1.0.0'\ndo:\n - answer:\n set:\n answer: 42\n"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. TAG_REQUIRED: A prerelease version requires an explicit publication tag (for example beta, not latest); the response hint lists the complete rules. TAG_INVALID: The tag is invalid: a prerelease cannot use latest; a tag may only use URL-safe characters (no spaces or / ? #); it cannot be a version or range; latest cannot be deleted. The response hint lists the complete rules. DEFINITION_INVALID: The source failed definition validation. INPUT_INVALID: The input does not satisfy the target contract or validation rules. SCHEDULE_INVALID: The schedule or time boundaries are invalid. TIMEZONE_INVALID: The timezone is not a valid IANA timezone. INTERVAL_TOO_SHORT: The schedule interval is shorter than one minute. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. VERSION_EXISTS: The version already exists with different source content. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. DEFINITION_IDENTITY_MISMATCH: The source identity or runtime language does not match the publication target. NO_MATCHING_VERSION: No published version matches the requested tag, version, or range. CYCLE_DETECTED: Publication would create a dependency cycle (A depends on B and B depends on A); the detail names the cycle path. |
| 429 | TRIGGER_LIMIT: The tenant has reached the limit of 100 enabled triggers. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Page through immutable schemas and locked dependencies in descending semantic-version order. Lists omit source by default; only expand=source includes full source, and other values return 400. Detail endpoints retain full source.
GET /automation/v1/workflows/{ns}/{name}/versions
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| query: limit | integer | optional; Page size: integer 1–100, default 25. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: expand | "source" | optional; Only source is accepted; source is omitted by default and other values return 400. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/versions" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.versions.list({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Workflow versions (source only with expand=source) on this page, ordered by semver descending. |
| data[].id | string | required; Version id, prefixed scv_ for scripts and wfv_ for workflows. |
| data[].kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[].version | string | required; Version number (semver, with +build metadata removed). |
| data[].digest | string | required; Content digest of the source and contract. |
| data[].source | string | optional; Full source of this version. Version lists omit it unless expand=source is given. |
| data[].input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| data[].input_schema.* (variant 5) | object | Recursive JSON value. |
| data[].input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].output_schema | object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| data[].output_schema.* (variant 5) | object | Recursive JSON value. |
| data[].output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].references | object[] | required; Actions, platform APIs, scripts and workflows this version depends on. Script and workflow dependencies are locked to exact versions at publication. |
| data[].references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| data[].references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| data[].references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| data[].references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| data[].outline | null / object[] | required; Step outline of a workflow as OutlineNode entries generated statically by the parser; null for scripts. |
| data[].outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| data[].outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| data[].outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| data[].outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| data[].outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| data[].outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| data[].outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| data[].outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| data[].outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| data[].outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| data[].outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| data[].outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| data[].outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| data[].outline (variant 2)[].children[] | object | Recursive JSON value. |
| data[].sdk_version | null / string | required; SDK version used when publishing a script; null for workflows. |
| data[].published_at | string | required; Publication time (RFC 3339 UTC). |
| data[].published_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| data[].published_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].published_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[].deprecated | null / string | required; Deprecation message, or null when not deprecated. A deprecated version still runs, but resolving a range or tag prefers versions that are not deprecated. |
| data[].deprecated_at | null / string | required; Time the version was deprecated (RFC 3339 UTC), or null. |
| data[].deprecated_by | null / object | required; Principal that deprecated the version, or null. |
| data[].deprecated_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].deprecated_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "wfv_00mv67m6x5409408c354944fa8a960d207eb33c297",
"kind": "workflow",
"version": "1.0.0",
"digest": "ea7352d51087eca0113ee82230848ce1506fd97d27aad4c7b1911e5c4ef9b5fb",
"input_schema": {},
"output_schema": {},
"references": [],
"outline": [
{
"name": "answer",
"reference": "/do/0/answer",
"kind": "set"
}
],
"sdk_version": null,
"published_at": "2026-10-13T04:57:32.297Z",
"published_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"deprecated": null,
"deprecated_at": null,
"deprecated_by": null
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read source, input/output schemas and deprecation details for an exact version. Missing versions return VERSION_NOT_FOUND. Details always return full source. version accepts an exact version or dist-tag; a range returns 400 with a hint to use /resolve.
GET /automation/v1/workflows/{ns}/{name}/versions/{version}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: version | string | required; Exact version or dist-tag; ranges are rejected with 400 and a hint. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/versions/1.0.0" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.versions.retrieve({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME"),
"version": "1.0.0"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Version id, prefixed scv_ for scripts and wfv_ for workflows. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| version | string | required; Version number (semver, with +build metadata removed). |
| digest | string | required; Content digest of the source and contract. |
| source | string | required; Full source of this version. Version lists omit it unless expand=source is given. |
| input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| input_schema.* (variant 5) | object | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| output_schema.* (variant 5) | object | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| references | object[] | required; Actions, platform APIs, scripts and workflows this version depends on. Script and workflow dependencies are locked to exact versions at publication. |
| references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| outline | null / object[] | required; Step outline of a workflow as OutlineNode entries generated statically by the parser; null for scripts. |
| outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| outline (variant 2)[].children[] | object | Recursive JSON value. |
| sdk_version | null / string | required; SDK version used when publishing a script; null for workflows. |
| published_at | string | required; Publication time (RFC 3339 UTC). |
| published_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| published_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| published_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| deprecated | null / string | required; Deprecation message, or null when not deprecated. A deprecated version still runs, but resolving a range or tag prefers versions that are not deprecated. |
| deprecated_at | null / string | required; Time the version was deprecated (RFC 3339 UTC), or null. |
| deprecated_by | null / object | required; Principal that deprecated the version, or null. |
| deprecated_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| deprecated_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"id": "wfv_00mv67m6x5409408c354944fa8a960d207eb33c297",
"kind": "workflow",
"version": "1.0.0",
"digest": "ea7352d51087eca0113ee82230848ce1506fd97d27aad4c7b1911e5c4ef9b5fb",
"input_schema": {},
"output_schema": {},
"references": [],
"outline": [
{
"name": "answer",
"reference": "/do/0/answer",
"kind": "set"
}
],
"sdk_version": null,
"published_at": "2026-10-13T04:57:32.297Z",
"published_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"deprecated": null,
"deprecated_at": null,
"deprecated_by": null,
"source": "document:\n dsl: '1.0.3'\n namespace: docs-samples\n name: sample-workflows-1791867412840-b05e8a\n version: '1.0.0'\ndo:\n - answer:\n set:\n answer: 42\n"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Record a deprecation message; an empty message removes deprecation without changing the version source.
POST /automation/v1/workflows/{ns}/{name}/versions/{version}/deprecate
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: version | string | required; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| message | string | required; Deprecation message; an empty string removes deprecation. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/versions/1.0.0/deprecate" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"message": ""
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.versions.deprecate({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME"),
"version": "1.0.0"
},
"body": {
"message": ""
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Version id, prefixed scv_ for scripts and wfv_ for workflows. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| version | string | required; Version number (semver, with +build metadata removed). |
| digest | string | required; Content digest of the source and contract. |
| source | string | required; Full source of this version. Version lists omit it unless expand=source is given. |
| input_schema | object | required; Any JSON object whose keys are strings and whose values are any JSON value. |
| input_schema.* (variant 5) | object | Recursive JSON value. |
| input_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| output_schema.* (variant 5) | object | Recursive JSON value. |
| output_schema.* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| references | object[] | required; Actions, platform APIs, scripts and workflows this version depends on. Script and workflow dependencies are locked to exact versions at publication. |
| references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| outline | null / object[] | required; Step outline of a workflow as OutlineNode entries generated statically by the parser; null for scripts. |
| outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| outline (variant 2)[].children[] | object | Recursive JSON value. |
| sdk_version | null / string | required; SDK version used when publishing a script; null for workflows. |
| published_at | string | required; Publication time (RFC 3339 UTC). |
| published_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| published_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| published_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| deprecated | null / string | required; Deprecation message, or null when not deprecated. A deprecated version still runs, but resolving a range or tag prefers versions that are not deprecated. |
| deprecated_at | null / string | required; Time the version was deprecated (RFC 3339 UTC), or null. |
| deprecated_by | null / object | required; Principal that deprecated the version, or null. |
| deprecated_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| deprecated_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"id": "wfv_00mv67m6x5409408c354944fa8a960d207eb33c297",
"kind": "workflow",
"version": "1.0.0",
"digest": "ea7352d51087eca0113ee82230848ce1506fd97d27aad4c7b1911e5c4ef9b5fb",
"input_schema": {},
"output_schema": {},
"references": [],
"outline": [
{
"name": "answer",
"reference": "/do/0/answer",
"kind": "set"
}
],
"sdk_version": null,
"published_at": "2026-10-13T04:57:32.297Z",
"published_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"deprecated": null,
"deprecated_at": null,
"deprecated_by": null,
"source": "document:\n dsl: '1.0.3'\n namespace: docs-samples\n name: sample-workflows-1791867412840-b05e8a\n version: '1.0.0'\ndo:\n - answer:\n set:\n answer: 42\n"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read the exact version for each distribution tag. Results include the update time and updater.
GET /automation/v1/workflows/{ns}/{name}/dist-tags
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/dist-tags" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.distTags.list({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| .*.version | string | required; Exact version the tag currently points to. |
| .*.updated_at | string | required; Time the tag was last moved (RFC 3339 UTC). |
| .*.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| .*.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| .*.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"latest": {
"version": "1.0.0",
"updated_at": "2026-10-13T04:57:32.297Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Point a distribution tag at an existing exact version; tags cannot be versions or version ranges. Moving latest can roll back a release and synchronizes workflow schedules.
PUT /automation/v1/workflows/{ns}/{name}/dist-tags/{tag}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: tag | string | required; Distribution tag. A prerelease (such as 1.3.0-beta.1) requires a tag and it cannot be latest; a tag may only use URL-safe characters (letters, digits and - _ . ! ~ * ' ( )), no spaces or / ? # and no leading or trailing whitespace; it cannot be a version or a version range (such as 1.2.3, ^1, 1.x, *); any other name such as beta, next or debug is allowed. Violations return TAG_INVALID or TAG_REQUIRED with the complete rules in hint. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| version | string | required; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X PUT "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/dist-tags/sample" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"version": "1.0.0"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.distTags.set({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME"),
"tag": "sample"
},
"body": {
"version": "1.0.0"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| .*.version | string | required; Exact version the tag currently points to. |
| .*.updated_at | string | required; Time the tag was last moved (RFC 3339 UTC). |
| .*.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| .*.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| .*.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"latest": {
"version": "1.0.0",
"updated_at": "2026-10-13T04:57:32.297Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
},
"sample": {
"version": "1.0.0",
"updated_at": "2026-10-13T04:57:36.329Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. TAG_INVALID: The tag is invalid: a prerelease cannot use latest; a tag may only use URL-safe characters (no spaces or / ? #); it cannot be a version or range; latest cannot be deleted. The response hint lists the complete rules. INPUT_INVALID: The input does not satisfy the target contract or validation rules. SCHEDULE_INVALID: The schedule or time boundaries are invalid. TIMEZONE_INVALID: The timezone is not a valid IANA timezone. INTERVAL_TOO_SHORT: The schedule interval is shorter than one minute. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 429 | TRIGGER_LIMIT: The tenant has reached the limit of 100 enabled triggers. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Delete a distribution tag while retaining versions. latest cannot be deleted, versions and ranges are invalid tags, and deleting an absent valid tag is repeatable.
DELETE /automation/v1/workflows/{ns}/{name}/dist-tags/{tag}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: ns | string | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | string | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| path: tag | string | required; Distribution tag. A prerelease (such as 1.3.0-beta.1) requires a tag and it cannot be latest; a tag may only use URL-safe characters (letters, digits and - _ . ! ~ * ' ( )), no spaces or / ? # and no leading or trailing whitespace; it cannot be a version or a version range (such as 1.2.3, ^1, 1.x, *); any other name such as beta, next or debug is allowed. Violations return TAG_INVALID or TAG_REQUIRED with the complete rules in hint. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| WORKFLOW_NAME | name returned by creating a workflow |
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X DELETE "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/dist-tags/sample" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.workflows.distTags.delete({
"path": {
"ns": "docs-samples",
"name": env("WORKFLOW_NAME"),
"tag": "sample"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| .*.version | string | required; Exact version the tag currently points to. |
| .*.updated_at | string | required; Time the tag was last moved (RFC 3339 UTC). |
| .*.updated_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| .*.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| .*.updated_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
HTTP 200
{
"latest": {
"version": "1.0.0",
"updated_at": "2026-10-13T04:57:32.297Z",
"updated_by": {
"type": "api_key",
"id": "key_3e00b8984967"
}
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. TAG_INVALID: The tag is invalid: a prerelease cannot use latest; a tag may only use URL-safe characters (no spaces or / ? #); it cannot be a version or range; latest cannot be deleted. The response hint lists the complete rules. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Check source without executing it when you need diagnostics, inferred schemas or references. This is optional before praxis.automation.runs.create, which also validates source before execution. Actions, scripts and workflows are supported; results include validity without saving. Invalid source is reported with valid=false. Script/action output schemas are inferred from return types: Promise unwrapping, Record, intersections and Date. Unknown types yield an empty schema and a warning in warnings. Source diagnostics use /source or /implementation/source with 1-based line/column. For kind=action the same admission checks as action creation apply (no external imports, platform operations only as direct call(praxis/., input) calls, no agent or automation calls), so source that validates is not rejected at creation.
POST /automation/v1/validate
Authorization: Bearer $PRAXIS_API_KEY
no additional fields.
| Field | Type | Description |
|---|---|---|
| kind | "action" / "script" / "workflow" | required; Source kind: action, script or workflow. |
| source | string | required; Source to validate: TypeScript for action/script, YAML for workflow. |
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/validate" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"kind": "script",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.validate.create({
"body": {
"kind": "script",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| valid | boolean | required; Whether the source passed validation: true means it can be published or run, false means see errors. |
| errors | object[] | required; Validation errors, each with pointer and a Chinese detail; empty when valid is true. |
| errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| input_schema | null / object | required; Input JSON Schema derived from the source, or null when the source cannot be parsed. |
| input_schema (variant 2).* (variant 5) | object | Recursive JSON value. |
| input_schema (variant 2).* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output_schema | null / object | required; Inferred from script return types, including Promise unwrapping, Record, intersections and Date (date-time); unresolved types yield an empty schema with a warning in /validate warnings. |
| output_schema (variant 2).* (variant 5) | object | Recursive JSON value. |
| output_schema (variant 2).* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| references | object[] | required; Actions, platform APIs, scripts and workflows the source depends on. |
| references[].kind | "action" / "script" / "workflow" / "platform_api" / "run" | required; Dependency kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow; run is the child-run target of an invoke("ns/name") call in a script (a script or workflow, resolved at publication). |
| references[].name | string | required; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| references[].range | string | optional; Version range or tag as written in the reference (npm rules); absent when none was written. |
| references[].locked_version | string | optional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked. |
| outline | null / object[] | required; Workflow step outline; null for scripts and actions. |
| outline (variant 2)[].name | string | required; Step name, the key of the step in the workflow YAML. |
| outline (variant 2)[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start; equals Task.reference at run time. |
| outline (variant 2)[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| outline (variant 2)[].target | string | optional; Target of the step: the action ns/name for a call step, ns/name@range for a run step; absent for other kinds. |
| outline (variant 2)[].wait | object | optional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields. |
| outline (variant 2)[].wait.until | string | optional; Absolute instant at which the wait ends, given only when it is statically known; the outline does not populate it today. |
| outline (variant 2)[].wait.seconds | number | optional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations. |
| outline (variant 2)[].wait.event | string | optional; Event type a listen step waits for. |
| outline (variant 2)[].wait.duration | string | optional; Original duration or runtime expression that cannot be statically converted to seconds. |
| outline (variant 2)[].loop | object | optional; Loop information {each, in} of a for step. no additional fields. |
| outline (variant 2)[].loop.each | string | required; Loop variable name; item when not specified. |
| outline (variant 2)[].loop.in | string | required; Verbatim expression of the collection being iterated. |
| outline (variant 2)[].children | object[] | optional; Nested child steps (inside do, fork branches, try and catch). |
| outline (variant 2)[].children[] | object | Recursive JSON value. |
| warnings | object[] | optional; Non-blocking script/action analysis diagnostics; an unknown type yields an empty schema and a warning. Workflow analysis may omit this field. |
| warnings[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| warnings[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| warnings[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| warnings[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| warnings[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| platform_apis | string[] | optional; Platform API names referenced by script/action analysis, as a string array; workflow analysis may omit this field. |
HTTP 200
{
"valid": true,
"errors": [],
"warnings": [],
"input_schema": {
"type": "object",
"properties": {
"n": {
"type": "number"
}
},
"required": [
"n"
]
},
"output_schema": {
"type": "object",
"properties": {
"answer": {
"type": "number"
}
},
"required": [
"answer"
]
},
"references": [],
"outline": null,
"platform_apis": []
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Resolve ns/name@tag, an exact version or a version range to a runnable exact version. Omitting @ selects latest; archived targets are rejected and no match returns NO_MATCHING_VERSION.
GET /automation/v1/resolve
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| query: target | string | required; ns/name@tag, ns/name@version or ns/name@range; omitting @ selects latest. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TARGET | Published docs-samples/name@1.0.0 |
: "${TARGET:?Set TARGET}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/resolve" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
--get \
--data-urlencode "target=${TARGET}"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.resolve.retrieve({
"query": {
"target": env("TARGET")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| namespace | string | required; Namespace of the resolved script or workflow. |
| name | string | required; Name of the resolved script or workflow. |
| version | string | required; Exact version number the target resolved to. |
| version_id | string | required; Id of that version (scv_ or wfv_ prefix). |
| deprecated | null / string | required; Deprecation message when the resolved version is deprecated; null otherwise. |
HTTP 200
{
"kind": "script",
"namespace": "docs-samples",
"name": "sample-scripts-1791867412840-b05e8a",
"version": "1.0.0",
"version_id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
"deprecated": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 422 | NO_MATCHING_VERSION: No published version matches the requested tag, version, or range. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Search visible targets and page in ascending name order. Archived targets are excluded by default; optionally select published scripts and workflows.
GET /automation/v1/targets
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| query: q | string | optional; Case-insensitive literal substring of ns/name or description. |
| query: kind | "action" / "script" / "workflow"[] | optional; action, script or workflow; omit for all. Separate multiple values with commas to match any value. minItems: 1 |
| query: limit | integer | optional; Page size: integer 1–100, default 25. minimum: 1; maximum: 100 |
| query: labels | object | optional; Filter using labels[k]=v; comma-separated values for one key match any, and different keys match together. |
| query: created_at[gte] | string | optional; Inclusive creation-time lower bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
| query: created_at[lte] | string | optional; Inclusive creation-time upper bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
| query: cursor | string | optional; Use next_cursor from the previous page and keep the same filters. |
| query: archived | boolean | optional; Defaults to false for active targets; true selects archived targets only. default: false |
| query: published | boolean | optional; When true, select definitions with at least one published version; actions are always available. |
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/targets" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
--get \
--data-urlencode "q=sample-" \
--data-urlencode "limit=1"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.targets.list({
"query": {
"q": "sample-",
"limit": 1
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Target hits across actions, scripts and workflows on this page, in search order. |
| data[].kind | "action" / "script" / "workflow" | required; Target kind. action is an action; script is a script; workflow is a workflow. |
| data[].namespace | string | required; Namespace of the target. |
| data[].name | string | required; Name of the target. |
| data[].description | string | required; Description of the target. |
| data[].latest_version | null / string | required; Version the latest tag points to; null for actions or when nothing is published. |
| data[].archived | boolean | required; true when the target is archived and can no longer be run. |
| next_cursor | string / null | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"kind": "action",
"namespace": "docs-samples",
"name": "sample-action-1791867412840-b05e8a",
"description": "",
"latest_version": null,
"archived": false
}
],
"next_cursor": "WyJbXCJ0YXJnZXRzXCIsXCJ0bnRfM2E5NzU5ODY0Y2NiNGUwMFwiLHtcInFcIjpcInNhbXBsZS1cIn1dIiwiZG9jcy1zYW1wbGVzL3NhbXBsZS1hY3Rpb24tMTc5MTg2NzQxMjg0MC1iMDVlOGEiLCJmdW5jdGlvbjphY3RfMDBtdjY3bG96NGZlNGYyN2JkZjg5MzQ2Yzg4NWIzYTI4YjIwMzhjMDkxIl0="
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Execute a published script or workflow with target, or test unpublished code directly with source and language (ts for TypeScript, yaml for workflow YAML), without first saving or publishing a definition. target and source are mutually exclusive; target accepts ns/name@version, @tag or @range and defaults to latest when @ is omitted. Source/input validation precedes run creation, so a separate validate call is optional. input defaults to {} and must match the input schema and fit within 1 MiB. wait is 0–60 seconds (default 0): a terminal run returns 200, otherwise 202. Use the returned id with praxis.automation.runs.retrieve and inspect status, output and error; acceptance does not mean successful completion. Idempotency-Key is scoped to tenant, method and path for 24 hours, excluding wait from the fingerprint; replay returns the current run with Idempotent-Replayed: true, changed contents return 422 and an in-flight request returns 409. New non-deterministic run IDs contain 78 characters (run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID), compared with 46 for legacy random IDs. Historical and deterministic IDs remain valid; same-millisecond order is not guaranteed. Minimal body: {"source":"export default async () => ({ok: true});","language":"ts","wait":10}.
POST /automation/v1/runs
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| header: Idempotency-Key | string | optional; 1–256 characters; deduplicates within tenant, method and path for 24 hours, excluding wait from the fingerprint. |
| Field | Type | Description |
|---|---|---|
| (variant 1).target | string | required; Script/workflow reference ns/name@tag, ns/name@version or ns/name@range; omission of @ selects latest. Mutually exclusive with source. |
| (variant 1).input | null / string / number / boolean / object / null / string / number / boolean / object / JSON[][] | optional; JSON run input, default {}; must satisfy the target input schema and fit within 1 MiB. |
| (variant 1).input (variant 5).* (variant 5) | object | Recursive JSON value. |
| (variant 1).input (variant 5).* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).input (variant 6)[] (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).input (variant 6)[] (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).wait | number | optional; Seconds to wait for a terminal state, 0–60, default 0; excluded from the idempotency fingerprint. minimum: 0; maximum: 60 |
| (variant 1).labels | object | optional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters. |
| (variant 1).deadline_seconds | integer | optional; Positive integer seconds up to 604,800. Scripts default to and are capped at 300 seconds; workflows default to 86,400 seconds and allow up to seven days. minimum: 1 |
| (variant 2).source | string | required; Source; for ad hoc runs it excludes target, requires language and is limited to 1 MiB. |
| (variant 2).language | "ts" / "yaml" | required; Source language: ts for scripts, yaml for workflows. |
| (variant 2).input | null / string / number / boolean / object / null / string / number / boolean / object / JSON[][] | optional; JSON run input, default {}; must satisfy the target input schema and fit within 1 MiB. |
| (variant 2).input (variant 5).* (variant 5) | object | Recursive JSON value. |
| (variant 2).input (variant 5).* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 2).input (variant 6)[] (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 2).input (variant 6)[] (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 2).wait | number | optional; Seconds to wait for a terminal state, 0–60, default 0; excluded from the idempotency fingerprint. minimum: 0; maximum: 60 |
| (variant 2).labels | object | optional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters. |
| (variant 2).deadline_seconds | integer | optional; Positive integer seconds up to 604,800. Scripts default to and are capped at 300 seconds; workflows default to 86,400 seconds and allow up to seven days. minimum: 1 |
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
"language": "ts",
"input": {
"n": 41
},
"wait": 60,
"labels": {
"namespace": "docs-samples",
"name": "sample-run"
}
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.create({
"body": {
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
"language": "ts",
"input": {
"n": 41
},
"wait": 60,
"labels": {
"namespace": "docs-samples",
"name": "sample-run"
}
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | true when returning a replayed run. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| definition (variant 2).name | string | required; Name of the script or workflow. |
| target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| counters | object | required; Cumulative counters of a run. no additional fields. |
| counters.calls | number | required; Total number of calls the script made. |
| counters.action_calls | number | required; How many of those calls invoked actions. |
| counters.child_runs | number | required; Number of child runs started. |
| counters.tasks_completed | number | required; Number of workflow steps completed. |
| counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| error | null / object | required; Error details when the run faulted; null otherwise. |
| error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| error (variant 2).title | string | required; Short error title. |
| error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| parent (variant 2).id | string | required; Id (run_) of the parent run. |
| parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| created_at | string | required; Time the run was created (RFC 3339 UTC). |
| started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| suspended_by | null / object | required; Principal that requested suspension, or null. |
| suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
Run accepted; still pending or executing when wait expires.
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | true when returning a replayed run. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| definition (variant 2).name | string | required; Name of the script or workflow. |
| target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| counters | object | required; Cumulative counters of a run. no additional fields. |
| counters.calls | number | required; Total number of calls the script made. |
| counters.action_calls | number | required; How many of those calls invoked actions. |
| counters.child_runs | number | required; Number of child runs started. |
| counters.tasks_completed | number | required; Number of workflow steps completed. |
| counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| error | null / object | required; Error details when the run faulted; null otherwise. |
| error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| error (variant 2).title | string | required; Short error title. |
| error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| parent (variant 2).id | string | required; Id (run_) of the parent run. |
| parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| created_at | string | required; Time the run was created (RFC 3339 UTC). |
| started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| suspended_by | null / object | required; Principal that requested suspension, or null. |
| suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
HTTP 200
{
"id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
"kind": "script",
"number": null,
"definition": null,
"target": null,
"resolved_version": null,
"source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
"language": "ts",
"status": "completed",
"progress": null,
"current_wait": null,
"counters": {
"calls": 0,
"action_calls": 0,
"child_runs": 0,
"tasks_completed": 0,
"tasks_total": null
},
"input": {
"n": 41
},
"output": {
"answer": 42
},
"error": null,
"initiator": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"channel": "api",
"owner": "tnt_3a9759864ccb4e00",
"trigger": null,
"parent": null,
"parent_run_id": null,
"root_run_id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
"depth": 0,
"attach": null,
"deadline_at": "2026-10-13T05:02:40.954Z",
"created_at": "2026-10-13T04:57:40.954Z",
"started_at": "2026-10-13T04:57:42.283Z",
"ended_at": "2026-10-13T04:57:42.367Z",
"updated_at": "2026-10-13T04:57:42.367Z",
"heartbeat_at": "2026-10-13T04:57:42.283Z",
"cancel_requested_at": null,
"cancelled_by": null,
"cancel_reason": null,
"cancel_message": null,
"suspend_requested_at": null,
"suspended_by": null,
"queued_ms": 1329,
"run_ms": 84,
"wait_ms": null,
"usage": null,
"rerun_of": null,
"labels": {
"namespace": "docs-samples",
"name": "sample-run-1791867412840-b05e8a"
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. DEFINITION_INVALID: The source failed definition validation. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| 409 | TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. |
| 413 | PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation. |
| 422 | NO_MATCHING_VERSION: No published version matches the requested tag, version, or range. IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Filter tenant runs and list them newest first. Filters include multiple statuses, target, origin, labels[k] and a creation-time lower bound. q matches a run ID exactly when it starts with run_; otherwise it matches a definition-name prefix. Large input/output values are null in lists with input_truncated/output_truncated true; get run details for full values.
GET /automation/v1/runs
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| query: limit | integer | optional; Page size: integer 1–100, default 50. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: kind | "script" / "workflow"[] | optional; script or workflow; omit for both. Separate multiple values with commas to match any value. minItems: 1 |
| query: definition | string[] | optional; Exact definition name in ns/name format. Separate multiple values with commas to match any value. minItems: 1 |
| query: version | string[] | optional; An exact canonical semantic version, such as 1.2.0 or 1.3.0-beta.1, not a range. Separate multiple values with commas to match any value. minItems: 1 |
| query: status | "pending" / "running" / "waiting" / "suspended" / "cancelled" / "faulted" / "completed"[] | optional; Comma-separated statuses: pending, running, waiting, suspended, cancelled, faulted, completed; omit for all. Separate multiple values with commas to match any value. |
| query: channel | "console" / "api" / "internal" / "run" / "trigger"[] | optional; Origin channel: run selects child runs; console, api, internal and trigger select root runs. Separate multiple values with commas to match any value. minItems: 1 |
| query: initiator_type | "user" / "api_key" / "agent" / "trigger"[] | optional; Root initiator type: user, api_key, agent or trigger, inherited by child runs. run returns INPUT_INVALID; filter origin with channel=run or parent_run_id. Separate multiple values with commas to match any value. minItems: 1 |
| query: initiator | "me" | optional; Only me is supported, matching the current credential subject type and ID, including child runs derived from my runs; omit for all. |
| query: adhoc | boolean | optional; true selects ad hoc runs, false published-definition runs; omit for both. |
| query: language | "ts" / "yaml"[] | optional; Source language: ts or yaml. Separate multiple values with commas to match any value. minItems: 1 |
| query: parent_run_id | string[] | optional; Match the direct parent run ID exactly; this lists the child runs of one run (started by a workflow run step or a script invoke()), each with its ID, target, status and timing. Separate multiple values with commas to match any value. minItems: 1 |
| query: root_run_id | string[] | optional; Match the root run ID exactly to filter a run tree. Separate multiple values with commas to match any value. minItems: 1 |
| query: q | string | optional; Exact run ID if starting with run_; otherwise a definition-name prefix. % and _ are literal characters. |
| query: labels | object | optional; Filter using labels[k]=v; comma-separated values for one key match any, and different keys match together. |
| query: created_at[gte] | string | optional; Inclusive creation-time lower bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
| query: created_at[lte] | string | optional; Inclusive creation-time upper bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
--get \
--data-urlencode "labels[name]=sample-run-1791867412840-b05e8a" \
--data-urlencode "limit=1"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.list({
"query": {
"labels": {
"name": "sample-run-1791867412840-b05e8a"
},
"limit": 1
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Run summaries on this page, ordered by created_at descending, then id descending. |
| data[].id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| data[].kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[].number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| data[].definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| data[].definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| data[].definition (variant 2).name | string | required; Name of the script or workflow. |
| data[].target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| data[].resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| data[].source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| data[].language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| data[].status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| data[].progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| data[].progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| data[].progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| data[].progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| data[].progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| data[].current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| data[].current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| data[].current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| data[].current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| data[].current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| data[].current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| data[].current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| data[].current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| data[].current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| data[].current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| data[].current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| data[].current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| data[].current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| data[].current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| data[].counters | object | required; Cumulative counters of a run. no additional fields. |
| data[].counters.calls | number | required; Total number of calls the script made. |
| data[].counters.action_calls | number | required; How many of those calls invoked actions. |
| data[].counters.child_runs | number | required; Number of child runs started. |
| data[].counters.tasks_completed | number | required; Number of workflow steps completed. |
| data[].counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| data[].input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[].input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[].output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].error | null / object | required; Error details when the run faulted; null otherwise. |
| data[].error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data[].error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data[].error (variant 2).title | string | required; Short error title. |
| data[].error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data[].error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data[].error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data[].error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data[].error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data[].error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data[].error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data[].error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data[].error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data[].error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data[].error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data[].error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data[].error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data[].error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data[].error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data[].error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data[].initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| data[].initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[].channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| data[].owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| data[].parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| data[].parent (variant 2).id | string | required; Id (run_) of the parent run. |
| data[].parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| data[].parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| data[].parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| data[].parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| data[].parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| data[].root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| data[].depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| data[].attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| data[].deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| data[].created_at | string | required; Time the run was created (RFC 3339 UTC). |
| data[].started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| data[].ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| data[].updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| data[].heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| data[].cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| data[].cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| data[].cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[].cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| data[].suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| data[].suspended_by | null / object | required; Principal that requested suspension, or null. |
| data[].suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[].queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| data[].run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| data[].wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| data[].usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| data[].usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| data[].usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| data[].usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| data[].usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| data[].usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| data[].usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| data[].usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| data[].rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| data[].labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| data[].trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| data[].trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| data[].trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| data[].cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| data[].input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| data[].output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
"kind": "script",
"number": null,
"definition": null,
"target": null,
"resolved_version": null,
"source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
"language": "ts",
"status": "completed",
"progress": null,
"current_wait": null,
"counters": {
"calls": 0,
"action_calls": 0,
"child_runs": 0,
"tasks_completed": 0,
"tasks_total": null
},
"input": {
"n": 41
},
"output": {
"answer": 42
},
"error": null,
"initiator": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"channel": "api",
"owner": "tnt_3a9759864ccb4e00",
"trigger": null,
"parent": null,
"parent_run_id": null,
"root_run_id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
"depth": 0,
"attach": null,
"deadline_at": "2026-10-13T05:02:40.954Z",
"created_at": "2026-10-13T04:57:40.954Z",
"started_at": "2026-10-13T04:57:42.283Z",
"ended_at": "2026-10-13T04:57:42.367Z",
"updated_at": "2026-10-13T04:57:42.367Z",
"heartbeat_at": "2026-10-13T04:57:42.283Z",
"cancel_requested_at": null,
"cancelled_by": null,
"cancel_reason": null,
"cancel_message": null,
"suspend_requested_at": null,
"suspended_by": null,
"queued_ms": 1329,
"run_ms": 84,
"wait_ms": null,
"usage": null,
"rerun_of": null,
"labels": {
"namespace": "docs-samples",
"name": "sample-run-1791867412840-b05e8a"
}
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read status, output and error for the id returned by praxis.automation.runs.create; output needs no expand option. A completed status confirms success; faulted and cancelled are terminal without successful completion. Optionally expand calls, tasks, task groups, logs or source in the same request. Pass wait (seconds, 0–60) to hold the request until the run is terminal or the time is up, instead of polling. Expanded pages hold at most 200 entries; use the ledger endpoints and cursors for subsequent pages. Workflow raise errors preserve the full type URI, status, title and detail; only internal platform exceptions are runtime errors.
GET /automation/v1/runs/{id}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: expand | "calls" / "tasks" / "task_groups" / "logs" / "source"[] | optional; Comma-separated, unique calls, tasks, task_groups, logs, source; these are all the valid values (output is not an expansion, the run output is the output field). Omitted by default. Expanded pages contain at most 200 entries. An invalid value returns INVALID_PARAMS listing the valid values. minItems: 1 |
| query: wait | integer | optional; Seconds to wait for the run to reach a terminal state, an integer 0–60, default 0 (return immediately). When the run is still pending, running or waiting after this time, the current run is returned with status 200; check status to tell. Above 60 or not an integer returns INVALID_PARAMS. Same meaning as wait on runs.create. minimum: 0; maximum: 60 |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.retrieve({
"path": {
"id": env("RUN_ID")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| definition (variant 2).name | string | required; Name of the script or workflow. |
| target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| counters | object | required; Cumulative counters of a run. no additional fields. |
| counters.calls | number | required; Total number of calls the script made. |
| counters.action_calls | number | required; How many of those calls invoked actions. |
| counters.child_runs | number | required; Number of child runs started. |
| counters.tasks_completed | number | required; Number of workflow steps completed. |
| counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| error | null / object | required; Error details when the run faulted; null otherwise. |
| error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| error (variant 2).title | string | required; Short error title. |
| error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| parent (variant 2).id | string | required; Id (run_) of the parent run. |
| parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| created_at | string | required; Time the run was created (RFC 3339 UTC). |
| started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| suspended_by | null / object | required; Principal that requested suspension, or null. |
| suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| calls | object | optional; Page of call records returned with expand=calls: {data, next_cursor}. no additional fields. |
| calls.data | object[] | required; Call records on this page. maxItems: 200 |
| calls.data[].id | string | required; Call id, prefixed call_. |
| calls.data[].run_id | string | required; Id (run_) of the script run that made the call. |
| calls.data[].seq | number | required; Position of the call within the run, increasing in call order; together with run_id it locates the call. |
| calls.data[].target | object | required; The target that was called: {kind, name, revision?, version?}. no additional fields. |
| calls.data[].target.kind | "action" / "script" / "workflow" / "platform_api" | required; Target kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow. |
| calls.data[].target.name | string | required; Target name: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| calls.data[].target.revision | string | optional; Id (actr_) of the action revision that executed; present only for action calls. |
| calls.data[].target.version | string | optional; Exact version that ran; present only for script and workflow calls. |
| calls.data[].args_preview | string | required; Single-line preview of the call arguments, truncated on the server; payloads over 32 KB are kept in object storage rather than inline. |
| calls.data[].result_preview | null / string | required; Single-line preview of the returned value, truncated on the server; null until the call ends. |
| calls.data[].status | "running" / "completed" / "faulted" / "cancelled" | required; Call status. running means still executing; completed means it returned normally; faulted means it failed and error explains why; cancelled means it was stopped because the run was cancelled. |
| calls.data[].started_at | string | required; Time the call started (RFC 3339 UTC). |
| calls.data[].ended_at | null / string | required; Time the call ended (RFC 3339 UTC), or null while it is running. |
| calls.data[].duration_ms | null / number | required; Milliseconds from start to end, or null while the call is running. |
| calls.data[].error | null / object | required; Error details when the call failed; null if it succeeded or is still running. |
| calls.data[].error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| calls.data[].error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| calls.data[].error (variant 2).title | string | required; Short error title. |
| calls.data[].error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| calls.data[].error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| calls.data[].error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| calls.data[].error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| calls.data[].error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| calls.data[].error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| calls.data[].error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| calls.data[].error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| calls.data[].error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| calls.data[].error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| calls.data[].error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| calls.data[].error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| calls.data[].error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| calls.data[].error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| calls.data[].error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| calls.data[].error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| calls.data[].child_run_id | null / string | required; When the target is a script or workflow, the id of the child run this call started; null for action and platform API calls. |
| calls.data[].invocation_key | string | required; Key identifying this logical call, sent downstream so that retries under at-least-once delivery can be deduplicated. |
| calls.data[].request_id | string / null | required; Downstream response X-Request-Id, or null before a response or when the header is absent. |
| calls.next_cursor | null / string | required; Cursor for the next page, or null when there are no more. |
| tasks | object | optional; Page of workflow steps returned with expand=tasks: {data, next_cursor}. no additional fields. |
| tasks.data | object[] | required; Steps on this page. maxItems: 200 |
| tasks.data[].id | string | required; Identifier of this step execution record; treat it as an opaque string. |
| tasks.data[].run_id | string | required; ID of the owning run. |
| tasks.data[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| tasks.data[].name | string | required; Step name, the key of the step in the workflow YAML. |
| tasks.data[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| tasks.data[].iteration | number[] | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| tasks.data[].attempt | number | required; Attempt number of this execution; it increases when the step is re-executed by a retry. |
| tasks.data[].status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| tasks.data[].skipped | boolean | required; true when the step was skipped without actually executing. |
| tasks.data[].started_at | null / string | required; Time the step started (RFC 3339 UTC), or null. |
| tasks.data[].ended_at | null / string | required; Time the step ended (RFC 3339 UTC), or null. |
| tasks.data[].duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| tasks.data[].input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| tasks.data[].input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| tasks.data[].input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| tasks.data[].input_truncated | boolean | required; true when input exceeded 32 KB and was truncated. |
| tasks.data[].output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| tasks.data[].output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| tasks.data[].output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| tasks.data[].output_truncated | boolean | required; True when output is omitted because it exceeds the inline limit. |
| tasks.data[].error | null / object | required; Error details when the step failed; null otherwise. |
| tasks.data[].error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| tasks.data[].error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| tasks.data[].error (variant 2).title | string | required; Short error title. |
| tasks.data[].error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| tasks.data[].error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| tasks.data[].error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| tasks.data[].error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| tasks.data[].error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| tasks.data[].error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| tasks.data[].error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| tasks.data[].error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| tasks.data[].error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| tasks.data[].error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| tasks.data[].error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| tasks.data[].error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| tasks.data[].error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| tasks.data[].error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| tasks.data[].error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| tasks.data[].error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| tasks.data[].action | null / object | required; Action {name, revision} a call step executed; null for other steps. |
| tasks.data[].action (variant 2).name | string | required; Full action name, ns/name. |
| tasks.data[].action (variant 2).revision | string | required; Id (actr_) of the action revision that ran. |
| tasks.data[].child_run | null / object | required; Summary {id, number, status, resolved_version} of the child run a run step started; null for other steps. |
| tasks.data[].child_run (variant 2).id | string | required; Id (run_) of the child run, readable as soon as it is created. |
| tasks.data[].child_run (variant 2).number | null / number | required; Sequence number of the child run within its definition; null for ad-hoc runs. |
| tasks.data[].child_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Status of the child run. pending is not started; running is executing; waiting is waiting; suspended is suspended; cancelled was cancelled; faulted failed; completed succeeded. An awaited child is updated to its terminal status when it ends; a detached child keeps the status at launch. |
| tasks.data[].child_run (variant 2).resolved_version | null / string | required; Exact version the child run resolved to; null for ad-hoc runs. |
| tasks.next_cursor | null / string | required; Cursor for the next page, or null when there are no more. |
| task_groups | object | optional; Page of steps aggregated by reference, returned with expand=task_groups as {data, next_cursor} (loop iterations collapse into one row); an empty page for script runs. no additional fields. |
| task_groups.data | object[] | required; Aggregated rows on this page. maxItems: 200 |
| task_groups.data[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| task_groups.data[].name | string | required; Step name, the key of the step in the workflow YAML. |
| task_groups.data[].count | number | required; Number of execution records merged under this reference (the loop iteration count). |
| task_groups.data[].status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| task_groups.data[].duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| task_groups.next_cursor | null / string | required; Cursor for the next page, or null when there are no more. |
| logs | object | optional; Page of log lines returned with expand=logs: {data, next_cursor}. no additional fields. |
| logs.data | object[] | required; Log lines on this page. maxItems: 200 |
| logs.data[].cursor | string | required; Cursor of this line; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| logs.data[].ts | string | required; Time the line was logged (RFC 3339 UTC). |
| logs.data[].level | "debug" / "info" / "warn" / "error" | required; Log level. debug is diagnostic detail; info is general information; warn is a warning; error is an error. |
| logs.data[].message | string | required; Log message text. |
| logs.next_cursor | null / string | required; Cursor for the next page, or null when there are no more. |
| source | object | optional; Source snapshot of an ad-hoc run as {language, source, sha256}. no additional fields. |
| source.language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| source.source | string | required; Full source (ts or yaml) the run used. |
| source.sha256 | string | required; SHA-256 digest of the source; usable as expected_source_sha256 when publishing. |
| cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
HTTP 200
{
"id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
"kind": "script",
"number": null,
"definition": null,
"target": null,
"resolved_version": null,
"source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
"language": "ts",
"status": "completed",
"progress": null,
"current_wait": null,
"counters": {
"calls": 0,
"action_calls": 0,
"child_runs": 0,
"tasks_completed": 0,
"tasks_total": null
},
"input": {
"n": 41
},
"output": {
"answer": 42
},
"error": null,
"initiator": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"channel": "api",
"owner": "tnt_3a9759864ccb4e00",
"trigger": null,
"parent": null,
"parent_run_id": null,
"root_run_id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
"depth": 0,
"attach": null,
"deadline_at": "2026-10-13T05:02:40.954Z",
"created_at": "2026-10-13T04:57:40.954Z",
"started_at": "2026-10-13T04:57:42.283Z",
"ended_at": "2026-10-13T04:57:42.367Z",
"updated_at": "2026-10-13T04:57:42.367Z",
"heartbeat_at": "2026-10-13T04:57:42.283Z",
"cancel_requested_at": null,
"cancelled_by": null,
"cancel_reason": null,
"cancel_message": null,
"suspend_requested_at": null,
"suspended_by": null,
"queued_ms": 1329,
"run_ms": 84,
"wait_ms": null,
"usage": {
"currency": "USD",
"cost": "0.000000",
"pending_events": 0,
"by_service": [],
"tree_cost": "0.000000"
},
"rerun_of": null,
"labels": {
"namespace": "docs-samples",
"name": "sample-run-1791867412840-b05e8a"
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Request run cancellation and return 202. Workflows terminate, while scripts receive an abort request followed by forced termination after a grace period. Terminal runs return 409 RUN_INVALID_STATE; cancellation propagates to attached children, not detached children. Optional reason contains 1–500 characters and is stored as Run.cancel_message; cancel_reason remains user.
POST /automation/v1/runs/{id}/cancel
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
no additional fields.
| Field | Type | Description |
|---|---|---|
| reason | string | optional; Optional cancellation note of 1–500 characters, stored as Run.cancel_message. cancel_reason remains user. minLength: 1; maxLength: 500 |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/cancel" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"reason": "Sample completed"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.cancel({
"path": {
"id": env("RUN_ID")
},
"body": {
"reason": "Sample completed"
}
});
console.log(result);Cancellation accepted; updated Run.
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| definition (variant 2).name | string | required; Name of the script or workflow. |
| target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| counters | object | required; Cumulative counters of a run. no additional fields. |
| counters.calls | number | required; Total number of calls the script made. |
| counters.action_calls | number | required; How many of those calls invoked actions. |
| counters.child_runs | number | required; Number of child runs started. |
| counters.tasks_completed | number | required; Number of workflow steps completed. |
| counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| error | null / object | required; Error details when the run faulted; null otherwise. |
| error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| error (variant 2).title | string | required; Short error title. |
| error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| parent (variant 2).id | string | required; Id (run_) of the parent run. |
| parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| created_at | string | required; Time the run was created (RFC 3339 UTC). |
| started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| suspended_by | null / object | required; Principal that requested suspension, or null. |
| suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
HTTP 202
{
"id": "run_00mv67mwcj0f099fa839644b384742cdfbbbff67226e46f1eed8a36c5226f15a3cf730a221",
"kind": "workflow",
"number": null,
"definition": null,
"target": null,
"resolved_version": null,
"source_digest": "fa40016c6458f18ae4e5b418247cdccccfc4d5dfabe2bdec76f3103842ea15ad",
"language": "yaml",
"status": "cancelled",
"progress": null,
"current_wait": null,
"counters": {
"calls": 0,
"action_calls": 0,
"child_runs": 0,
"tasks_completed": 0,
"tasks_total": 1
},
"input": {},
"output": null,
"error": null,
"initiator": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"channel": "api",
"owner": "tnt_3a9759864ccb4e00",
"trigger": null,
"parent": null,
"parent_run_id": null,
"root_run_id": "run_00mv67mwcj0f099fa839644b384742cdfbbbff67226e46f1eed8a36c5226f15a3cf730a221",
"depth": 0,
"attach": null,
"deadline_at": "2026-10-14T04:58:05.251Z",
"created_at": "2026-10-13T04:58:05.251Z",
"started_at": null,
"ended_at": "2026-10-13T04:58:07.803Z",
"updated_at": "2026-10-13T04:58:07.803Z",
"heartbeat_at": null,
"cancel_requested_at": "2026-10-13T04:58:07.754Z",
"cancelled_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"cancel_reason": "user",
"cancel_message": "Sample completed",
"suspend_requested_at": null,
"suspended_by": null,
"queued_ms": 2552,
"run_ms": 0,
"wait_ms": null,
"usage": null,
"rerun_of": null,
"labels": {
"namespace": "docs-samples",
"name": "sample-run-1791867412840-b05e8a"
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| 409 | RUN_INVALID_STATE: The current state does not allow this action. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Create a new root run from the original exact version or ad hoc source, retaining labels and setting rerun_of. Override input or omit it to reuse the original input; archived targets and run tokens are rejected.
POST /automation/v1/runs/{id}/rerun
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
no additional fields.
| Field | Type | Description |
|---|---|---|
| input | null / string / number / boolean / object / null / string / number / boolean / object / JSON[][] | optional; Optional replacement input; omit to reuse the original run input. Must satisfy the target schema. |
| input (variant 5).* (variant 5) | object | Recursive JSON value. |
| input (variant 5).* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/rerun" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"input": {
"n": 42
}
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.rerun({
"path": {
"id": env("RUN_ID")
},
"body": {
"input": {
"n": 42
}
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| definition (variant 2).name | string | required; Name of the script or workflow. |
| target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| counters | object | required; Cumulative counters of a run. no additional fields. |
| counters.calls | number | required; Total number of calls the script made. |
| counters.action_calls | number | required; How many of those calls invoked actions. |
| counters.child_runs | number | required; Number of child runs started. |
| counters.tasks_completed | number | required; Number of workflow steps completed. |
| counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| error | null / object | required; Error details when the run faulted; null otherwise. |
| error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| error (variant 2).title | string | required; Short error title. |
| error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| parent (variant 2).id | string | required; Id (run_) of the parent run. |
| parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| created_at | string | required; Time the run was created (RFC 3339 UTC). |
| started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| suspended_by | null / object | required; Principal that requested suspension, or null. |
| suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
HTTP 200
{
"id": "run_00mv67mj3s5141d7514d6e0c18cd71ba7e821b89faadad8897cc6bedb103209efe6de40b4d",
"kind": "script",
"number": null,
"definition": null,
"target": null,
"resolved_version": null,
"source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
"language": "ts",
"status": "running",
"progress": null,
"current_wait": null,
"counters": {
"calls": 0,
"action_calls": 0,
"child_runs": 0,
"tasks_completed": 0,
"tasks_total": null
},
"input": {
"n": 42
},
"output": null,
"error": null,
"initiator": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"channel": "api",
"owner": "tnt_3a9759864ccb4e00",
"trigger": null,
"parent": null,
"parent_run_id": null,
"root_run_id": "run_00mv67mj3s5141d7514d6e0c18cd71ba7e821b89faadad8897cc6bedb103209efe6de40b4d",
"depth": 0,
"attach": null,
"deadline_at": "2026-10-13T05:02:48.088Z",
"created_at": "2026-10-13T04:57:48.088Z",
"started_at": "2026-10-13T04:57:49.075Z",
"ended_at": null,
"updated_at": "2026-10-13T04:57:49.075Z",
"heartbeat_at": "2026-10-13T04:57:49.075Z",
"cancel_requested_at": null,
"cancelled_by": null,
"cancel_reason": null,
"cancel_message": null,
"suspend_requested_at": null,
"suspended_by": null,
"queued_ms": 987,
"run_ms": null,
"wait_ms": null,
"usage": null,
"rerun_of": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
"labels": {
"namespace": "docs-samples",
"name": "sample-run-1791867412840-b05e8a"
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. DEFINITION_INVALID: The source failed definition validation. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| 403 | NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 413 | PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. NO_MATCHING_VERSION: No published version matches the requested tag, version, or range. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Suspend only a running or waiting workflow. Scripts return OPERATION_NOT_SUPPORTED; other states return RUN_INVALID_STATE.
POST /automation/v1/runs/{id}/suspend
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
no additional fields. object
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/suspend" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.suspend({
"path": {
"id": env("RUN_ID")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| definition (variant 2).name | string | required; Name of the script or workflow. |
| target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| counters | object | required; Cumulative counters of a run. no additional fields. |
| counters.calls | number | required; Total number of calls the script made. |
| counters.action_calls | number | required; How many of those calls invoked actions. |
| counters.child_runs | number | required; Number of child runs started. |
| counters.tasks_completed | number | required; Number of workflow steps completed. |
| counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| error | null / object | required; Error details when the run faulted; null otherwise. |
| error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| error (variant 2).title | string | required; Short error title. |
| error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| parent (variant 2).id | string | required; Id (run_) of the parent run. |
| parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| created_at | string | required; Time the run was created (RFC 3339 UTC). |
| started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| suspended_by | null / object | required; Principal that requested suspension, or null. |
| suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
HTTP 200
{
"id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
"kind": "workflow",
"number": null,
"definition": null,
"target": null,
"resolved_version": null,
"source_digest": "1f559f7323adda4865d889639a4d878eab97e1ce3e542c68ea4022af4cd0f7fa",
"language": "yaml",
"status": "suspended",
"progress": null,
"current_wait": {
"id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
"run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
"kind": "event",
"state": "open",
"task": {
"reference": "/do/0/ready",
"name": "ready"
},
"resume_at": null,
"event_type": "ready",
"child_run_id": null,
"created_at": "2026-10-13T04:57:56.982Z",
"expires_at": "2026-10-14T04:57:50.405Z",
"resolved_at": null
},
"counters": {
"calls": 0,
"action_calls": 0,
"child_runs": 0,
"tasks_completed": 0,
"tasks_total": 1
},
"input": {},
"output": null,
"error": null,
"initiator": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"channel": "api",
"owner": "tnt_3a9759864ccb4e00",
"trigger": null,
"parent": null,
"parent_run_id": null,
"root_run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
"depth": 0,
"attach": null,
"deadline_at": "2026-10-14T04:57:50.405Z",
"created_at": "2026-10-13T04:57:50.405Z",
"started_at": "2026-10-13T04:57:56.933Z",
"ended_at": null,
"updated_at": "2026-10-13T04:57:58.173Z",
"heartbeat_at": null,
"cancel_requested_at": null,
"cancelled_by": null,
"cancel_reason": null,
"cancel_message": null,
"suspend_requested_at": "2026-10-13T04:57:58.173Z",
"suspended_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"queued_ms": 6528,
"run_ms": null,
"wait_ms": null,
"usage": null,
"rerun_of": null,
"labels": {
"namespace": "docs-samples",
"name": "sample-run-1791867412840-b05e8a"
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| 409 | OPERATION_NOT_SUPPORTED: This resource type does not support the operation. RUN_INVALID_STATE: The current state does not allow this action. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Resume only a suspended workflow to its prior running or waiting state. It remains suspended if concurrency slots are unavailable; scripts do not support this operation.
POST /automation/v1/runs/{id}/resume
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
no additional fields. object
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/resume" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.resume({
"path": {
"id": env("RUN_ID")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| definition (variant 2).name | string | required; Name of the script or workflow. |
| target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| counters | object | required; Cumulative counters of a run. no additional fields. |
| counters.calls | number | required; Total number of calls the script made. |
| counters.action_calls | number | required; How many of those calls invoked actions. |
| counters.child_runs | number | required; Number of child runs started. |
| counters.tasks_completed | number | required; Number of workflow steps completed. |
| counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| error | null / object | required; Error details when the run faulted; null otherwise. |
| error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| error (variant 2).title | string | required; Short error title. |
| error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| parent (variant 2).id | string | required; Id (run_) of the parent run. |
| parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| created_at | string | required; Time the run was created (RFC 3339 UTC). |
| started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| suspended_by | null / object | required; Principal that requested suspension, or null. |
| suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
HTTP 200
{
"id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
"kind": "workflow",
"number": null,
"definition": null,
"target": null,
"resolved_version": null,
"source_digest": "1f559f7323adda4865d889639a4d878eab97e1ce3e542c68ea4022af4cd0f7fa",
"language": "yaml",
"status": "waiting",
"progress": null,
"current_wait": {
"id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
"run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
"kind": "event",
"state": "open",
"task": {
"reference": "/do/0/ready",
"name": "ready"
},
"resume_at": null,
"event_type": "ready",
"child_run_id": null,
"created_at": "2026-10-13T04:57:56.982Z",
"expires_at": "2026-10-14T04:57:50.405Z",
"resolved_at": null
},
"counters": {
"calls": 0,
"action_calls": 0,
"child_runs": 0,
"tasks_completed": 0,
"tasks_total": 1
},
"input": {},
"output": null,
"error": null,
"initiator": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"channel": "api",
"owner": "tnt_3a9759864ccb4e00",
"trigger": null,
"parent": null,
"parent_run_id": null,
"root_run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
"depth": 0,
"attach": null,
"deadline_at": "2026-10-14T04:57:50.405Z",
"created_at": "2026-10-13T04:57:50.405Z",
"started_at": "2026-10-13T04:57:56.933Z",
"ended_at": null,
"updated_at": "2026-10-13T04:58:02.193Z",
"heartbeat_at": null,
"cancel_requested_at": null,
"cancelled_by": null,
"cancel_reason": null,
"cancel_message": null,
"suspend_requested_at": null,
"suspended_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"queued_ms": 6528,
"run_ms": null,
"wait_ms": null,
"usage": null,
"rerun_of": null,
"labels": {
"namespace": "docs-samples",
"name": "sample-run-1791867412840-b05e8a"
}
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| 409 | OPERATION_NOT_SUPPORTED: This resource type does not support the operation. RUN_INVALID_STATE: The current state does not allow this action. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
List current and historical waits in ledger order. Wait types include event, timer and child.
GET /automation/v1/runs/{id}/waits
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: limit | integer | optional; Page size: integer 1–100, default 50. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/waits" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.waits.list({
"path": {
"id": env("RUN_ID")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Wait points, current and historical on this page, ordered by created_at descending, then id descending. |
| data[].id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| data[].run_id | string | required; Id (run_) of the run this wait belongs to. |
| data[].kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| data[].state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| data[].task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| data[].task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| data[].task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| data[].resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| data[].event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| data[].child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| data[].created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| data[].expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| data[].resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
"run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
"kind": "event",
"state": "open",
"task": {
"reference": "/do/0/ready",
"name": "ready"
},
"resume_at": null,
"event_type": "ready",
"child_run_id": null,
"created_at": "2026-10-13T04:57:56.982Z",
"expires_at": "2026-10-14T04:57:50.405Z",
"resolved_at": null
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Page through the call ledger with execution results. Entries follow ledger order and include targets, argument/result previews, statuses and durations. Script runs read the call ledger; a workflow run records its action calls on its tasks, so this lists the action tasks (skipped ones excluded), matching counters.action_calls.
GET /automation/v1/runs/{id}/calls
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: limit | integer | optional; Run ledger page size: integer 1–200, default 50; other collections are capped at 100. minimum: 1; maximum: 200 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/calls" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.calls.list({
"path": {
"id": env("RUN_ID")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Script call records on this page, ordered by seq. |
| data[].id | string | required; Call id, prefixed call_. |
| data[].run_id | string | required; Id (run_) of the script run that made the call. |
| data[].seq | number | required; Position of the call within the run, increasing in call order; together with run_id it locates the call. |
| data[].target | object | required; The target that was called: {kind, name, revision?, version?}. no additional fields. |
| data[].target.kind | "action" / "script" / "workflow" / "platform_api" | required; Target kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow. |
| data[].target.name | string | required; Target name: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| data[].target.revision | string | optional; Id (actr_) of the action revision that executed; present only for action calls. |
| data[].target.version | string | optional; Exact version that ran; present only for script and workflow calls. |
| data[].args_preview | string | required; Single-line preview of the call arguments, truncated on the server; payloads over 32 KB are kept in object storage rather than inline. |
| data[].result_preview | null / string | required; Single-line preview of the returned value, truncated on the server; null until the call ends. |
| data[].status | "running" / "completed" / "faulted" / "cancelled" | required; Call status. running means still executing; completed means it returned normally; faulted means it failed and error explains why; cancelled means it was stopped because the run was cancelled. |
| data[].started_at | string | required; Time the call started (RFC 3339 UTC). |
| data[].ended_at | null / string | required; Time the call ended (RFC 3339 UTC), or null while it is running. |
| data[].duration_ms | null / number | required; Milliseconds from start to end, or null while the call is running. |
| data[].error | null / object | required; Error details when the call failed; null if it succeeded or is still running. |
| data[].error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data[].error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data[].error (variant 2).title | string | required; Short error title. |
| data[].error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data[].error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data[].error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data[].error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data[].error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data[].error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data[].error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data[].error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data[].error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data[].error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data[].error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data[].error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data[].error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data[].error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data[].error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data[].error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data[].child_run_id | null / string | required; When the target is a script or workflow, the id of the child run this call started; null for action and platform API calls. |
| data[].invocation_key | string | required; Key identifying this logical call, sent downstream so that retries under at-least-once delivery can be deduplicated. |
| data[].request_id | string / null | required; Downstream response X-Request-Id, or null before a response or when the header is absent. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read run artifacts and their file references. Entries follow ledger order and include content types, sizes and associated steps.
GET /automation/v1/runs/{id}/artifacts
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: limit | integer | optional; Page size: integer 1–100, default 50. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/artifacts" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.artifacts.list({
"path": {
"id": env("RUN_ID")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Run artifacts on this page, ordered by created_at descending, then id descending. |
| data[].id | string | required; Artifact id; treat it as an opaque string. |
| data[].file_id | string | required; Id of the artifact in the file service; download the content through the files API. |
| data[].name | string | required; File name of the artifact. |
| data[].content_type | string | required; MIME type of the artifact. |
| data[].size_in_bytes | number | required; Size of the artifact in bytes. |
| data[].task | null / string | required; JSON Pointer of the workflow step that produced the artifact, or null when it did not come from a step. |
| data[].created_at | string | required; Time the artifact was created (RFC 3339 UTC). |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Complete only an event wait with a payload of at most 32 KiB satisfying its filter; timer and child waits cannot be completed manually. Reusing the same id and payload returns replayed=true; other repeats return WAIT_ALREADY_RESOLVED and expired waits return WAIT_EXPIRED.
POST /automation/v1/runs/{id}/waits/{wait_id}/complete
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| path: wait_id | string | required; Wait ID (wait_) belonging to this run. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| id | string | optional; Optional event deduplication ID; repeating the same ID and payload for this wait returns replayed=true. |
| payload | null / string / number / boolean / object / null / string / number / boolean / object / JSON[][] | required; Event data, at most 32 KiB when JSON-encoded; must satisfy the wait filter. |
| payload (variant 5).* (variant 5) | object | Recursive JSON value. |
| payload (variant 5).* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| payload (variant 6)[] (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| payload (variant 6)[] (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
| WAIT_ID | Wait id from the same run with kind=event and state=open |
: "${RUN_ID:?Set RUN_ID}"
: "${WAIT_ID:?Set WAIT_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/waits/${WAIT_ID}/complete" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"payload": {
"answer": 42
}
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.waits.complete({
"path": {
"id": env("RUN_ID"),
"wait_id": env("WAIT_ID")
},
"body": {
"payload": {
"answer": 42
}
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Wait point id, prefixed wait_. |
| run_id | string | required; Id (run_) of the run the wait belongs to. |
| kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event; timer waits until a time; child waits for a child run. This endpoint only works on event waits. |
| state | "cancelled" / "open" / "resolved" / "expired" | required; Wait state after the call. open is still waiting; resolved was satisfied; expired passed its deadline; cancelled was cancelled. A successfully submitted event leaves it resolved. |
| task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is none. |
| task (variant 2).reference | string | required; JSON Pointer of the step. |
| task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC). |
| replayed | boolean | required; true when this was a repeated submission with the same id and payload, so the original result is returned instead of processing it again. |
HTTP 200
{
"id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
"run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
"kind": "event",
"state": "resolved",
"task": {
"reference": "/do/0/ready",
"name": "ready"
},
"resume_at": null,
"event_type": "ready",
"child_run_id": null,
"created_at": "2026-10-13T04:57:56.982Z",
"expires_at": "2026-10-14T04:57:50.405Z",
"resolved_at": "2026-10-13T04:58:03.972Z",
"replayed": false
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. WAIT_NOT_FOUND: The wait point does not exist in this run. |
| 409 | OPERATION_NOT_SUPPORTED: This resource type does not support the operation. WAIT_ALREADY_RESOLVED: The wait point is closed, or a repeated event differs from the original submission. |
| 410 | WAIT_EXPIRED: The wait point has expired. |
| 413 | PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Page through the task ledger. include=planned adds unexecuted top-level steps; group_by=reference aggregates count, status and duration by task reference.
GET /automation/v1/runs/{id}/tasks
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: limit | integer | optional; Run ledger page size: integer 1–200, default 50; other collections are capped at 100. minimum: 1; maximum: 200 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: include | "planned" | optional; Only planned is supported, adding unexecuted top-level steps; omit to read existing tasks only. |
| query: group_by | "reference" | optional; Only reference is supported, grouping loop executions by task reference; omit for individual tasks. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/tasks" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.tasks.list({
"path": {
"id": env("RUN_ID")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object / object[] | required; Workflow step records, or TaskGroup rows aggregated by reference when group_by=reference on this page, in execution order. |
| data[] (variant 1).id | string | required; Identifier of this step execution record; treat it as an opaque string. |
| data[] (variant 1).run_id | string | required; ID of the owning run. |
| data[] (variant 1).reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| data[] (variant 1).name | string | required; Step name, the key of the step in the workflow YAML. |
| data[] (variant 1).kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| data[] (variant 1).iteration | number[] | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| data[] (variant 1).attempt | number | required; Attempt number of this execution; it increases when the step is re-executed by a retry. |
| data[] (variant 1).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| data[] (variant 1).skipped | boolean | required; true when the step was skipped without actually executing. |
| data[] (variant 1).started_at | null / string | required; Time the step started (RFC 3339 UTC), or null. |
| data[] (variant 1).ended_at | null / string | required; Time the step ended (RFC 3339 UTC), or null. |
| data[] (variant 1).duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| data[] (variant 1).input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[] (variant 1).input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).input_truncated | boolean | required; true when input exceeded 32 KB and was truncated. |
| data[] (variant 1).output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[] (variant 1).output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).output_truncated | boolean | required; True when output is omitted because it exceeds the inline limit. |
| data[] (variant 1).error | null / object | required; Error details when the step failed; null otherwise. |
| data[] (variant 1).error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data[] (variant 1).error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data[] (variant 1).error (variant 2).title | string | required; Short error title. |
| data[] (variant 1).error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data[] (variant 1).error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data[] (variant 1).error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data[] (variant 1).error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data[] (variant 1).error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data[] (variant 1).error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data[] (variant 1).error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data[] (variant 1).error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data[] (variant 1).error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data[] (variant 1).error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data[] (variant 1).error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data[] (variant 1).error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data[] (variant 1).error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data[] (variant 1).error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 1).error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 1).error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data[] (variant 1).action | null / object | required; Action {name, revision} a call step executed; null for other steps. |
| data[] (variant 1).action (variant 2).name | string | required; Full action name, ns/name. |
| data[] (variant 1).action (variant 2).revision | string | required; Id (actr_) of the action revision that ran. |
| data[] (variant 1).child_run | null / object | required; Summary {id, number, status, resolved_version} of the child run a run step started; null for other steps. |
| data[] (variant 1).child_run (variant 2).id | string | required; Id (run_) of the child run, readable as soon as it is created. |
| data[] (variant 1).child_run (variant 2).number | null / number | required; Sequence number of the child run within its definition; null for ad-hoc runs. |
| data[] (variant 1).child_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Status of the child run. pending is not started; running is executing; waiting is waiting; suspended is suspended; cancelled was cancelled; faulted failed; completed succeeded. An awaited child is updated to its terminal status when it ends; a detached child keeps the status at launch. |
| data[] (variant 1).child_run (variant 2).resolved_version | null / string | required; Exact version the child run resolved to; null for ad-hoc runs. |
| data[] (variant 2).reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| data[] (variant 2).name | string | required; Step name, the key of the step in the workflow YAML. |
| data[] (variant 2).count | number | required; Number of execution records merged under this reference (the loop iteration count). |
| data[] (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| data[] (variant 2).duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read the CloudEvents ledger or subscribe to live events. Return a CloudEvents ledger page by default; Accept: text/event-stream opens a live stream with ai.praxis.automation.run.status, ai.praxis.automation.run.progress, ai.praxis.automation.call.started, ai.praxis.automation.call.completed, ai.praxis.automation.task.started, ai.praxis.automation.task.completed and ai.praxis.automation.wait.created, ai.praxis.automation.wait.resolved event names. id is the resume cursor and Last-Event-ID takes precedence over cursor; : ping arrives every 20 seconds and event: end closes the stream after a terminal run.
GET /automation/v1/runs/{id}/events
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: limit | integer | optional; Page size: integer 1–100, default 50. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| header: Accept | "application/json" / "text/event-stream" | optional; application/json (default) reads a ledger page; text/event-stream subscribes to the live stream. |
| header: Last-Event-ID | string | optional; SSE resume cursor; read entries after this event. Takes precedence over cursor and applies only to streams. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/events" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Accept: text/event-stream"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
for await (const event of automation.runs.events({
"path": {
"id": env("RUN_ID")
}
})) {
console.log(event);
}Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object / object / object / object / object[] | required; Ledger events (RunEvent) on this page, in ledger order. |
| data[] (variant 1).type | "ai.praxis.automation.run.status" | required; Event type: always ai.praxis.automation.run.status, the run status changed; data is the full run. |
| data[] (variant 1).data | object | required; Full state of one run: target, status, input and output, error, initiator, position in the run tree and its timestamps. no additional fields. |
| data[] (variant 1).data.id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| data[] (variant 1).data.kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[] (variant 1).data.number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| data[] (variant 1).data.definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| data[] (variant 1).data.definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| data[] (variant 1).data.definition (variant 2).name | string | required; Name of the script or workflow. |
| data[] (variant 1).data.target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| data[] (variant 1).data.resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| data[] (variant 1).data.source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| data[] (variant 1).data.language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| data[] (variant 1).data.status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| data[] (variant 1).data.progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| data[] (variant 1).data.progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| data[] (variant 1).data.progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| data[] (variant 1).data.progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| data[] (variant 1).data.progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| data[] (variant 1).data.current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| data[] (variant 1).data.current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| data[] (variant 1).data.current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| data[] (variant 1).data.current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| data[] (variant 1).data.current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| data[] (variant 1).data.current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| data[] (variant 1).data.current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| data[] (variant 1).data.current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| data[] (variant 1).data.current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| data[] (variant 1).data.current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| data[] (variant 1).data.current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| data[] (variant 1).data.current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| data[] (variant 1).data.current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| data[] (variant 1).data.current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| data[] (variant 1).data.counters | object | required; Cumulative counters of a run. no additional fields. |
| data[] (variant 1).data.counters.calls | number | required; Total number of calls the script made. |
| data[] (variant 1).data.counters.action_calls | number | required; How many of those calls invoked actions. |
| data[] (variant 1).data.counters.child_runs | number | required; Number of child runs started. |
| data[] (variant 1).data.counters.tasks_completed | number | required; Number of workflow steps completed. |
| data[] (variant 1).data.counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| data[] (variant 1).data.input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[] (variant 1).data.input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).data.input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).data.output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[] (variant 1).data.output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).data.output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).data.error | null / object | required; Error details when the run faulted; null otherwise. |
| data[] (variant 1).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data[] (variant 1).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data[] (variant 1).data.error (variant 2).title | string | required; Short error title. |
| data[] (variant 1).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data[] (variant 1).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data[] (variant 1).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data[] (variant 1).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data[] (variant 1).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data[] (variant 1).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data[] (variant 1).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data[] (variant 1).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data[] (variant 1).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data[] (variant 1).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data[] (variant 1).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data[] (variant 1).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data[] (variant 1).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data[] (variant 1).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 1).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 1).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data[] (variant 1).data.initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| data[] (variant 1).data.initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[] (variant 1).data.initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[] (variant 1).data.channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| data[] (variant 1).data.owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| data[] (variant 1).data.parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| data[] (variant 1).data.parent (variant 2).id | string | required; Id (run_) of the parent run. |
| data[] (variant 1).data.parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| data[] (variant 1).data.parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| data[] (variant 1).data.parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| data[] (variant 1).data.parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| data[] (variant 1).data.parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| data[] (variant 1).data.root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| data[] (variant 1).data.depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| data[] (variant 1).data.attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| data[] (variant 1).data.deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| data[] (variant 1).data.created_at | string | required; Time the run was created (RFC 3339 UTC). |
| data[] (variant 1).data.started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| data[] (variant 1).data.ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| data[] (variant 1).data.updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| data[] (variant 1).data.heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| data[] (variant 1).data.cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| data[] (variant 1).data.cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| data[] (variant 1).data.cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[] (variant 1).data.cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[] (variant 1).data.cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| data[] (variant 1).data.suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| data[] (variant 1).data.suspended_by | null / object | required; Principal that requested suspension, or null. |
| data[] (variant 1).data.suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[] (variant 1).data.suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[] (variant 1).data.queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| data[] (variant 1).data.run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| data[] (variant 1).data.wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| data[] (variant 1).data.usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| data[] (variant 1).data.usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| data[] (variant 1).data.usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| data[] (variant 1).data.usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| data[] (variant 1).data.usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| data[] (variant 1).data.usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| data[] (variant 1).data.usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| data[] (variant 1).data.usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| data[] (variant 1).data.rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| data[] (variant 1).data.labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| data[] (variant 1).data.trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| data[] (variant 1).data.trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| data[] (variant 1).data.trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| data[] (variant 1).data.cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| data[] (variant 1).data.input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| data[] (variant 1).data.output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
| data[] (variant 1).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data[] (variant 1).id | string | required; Event id, unique within the run's ledger. |
| data[] (variant 1).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data[] (variant 1).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data[] (variant 1).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data[] (variant 1).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| data[] (variant 2).type | "ai.praxis.automation.run.progress" | required; Event type: always ai.praxis.automation.run.progress, the run reported new progress; data is the progress. |
| data[] (variant 2).data | object | required; Progress reported by a run: a label, the amount completed and the total. no additional fields. |
| data[] (variant 2).data.label | string | required; Short progress label, such as the current stage. |
| data[] (variant 2).data.current | null / number | required; Amount completed so far, or null if not reported. |
| data[] (variant 2).data.total | null / number | required; Total amount, or null when unknown. |
| data[] (variant 2).data.updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| data[] (variant 2).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data[] (variant 2).id | string | required; Event id, unique within the run's ledger. |
| data[] (variant 2).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data[] (variant 2).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data[] (variant 2).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data[] (variant 2).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| data[] (variant 3).type | "ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed" | required; Event type. ai.praxis.automation.call.started means a call started; ai.praxis.automation.call.completed means a call ended, successfully or not; data is the call record. |
| data[] (variant 3).data | object | required; Record of one call made during a script run (an action, platform API, script or workflow), ordered by seq. no additional fields. |
| data[] (variant 3).data.id | string | required; Call id, prefixed call_. |
| data[] (variant 3).data.run_id | string | required; Id (run_) of the script run that made the call. |
| data[] (variant 3).data.seq | number | required; Position of the call within the run, increasing in call order; together with run_id it locates the call. |
| data[] (variant 3).data.target | object | required; The target that was called: {kind, name, revision?, version?}. no additional fields. |
| data[] (variant 3).data.target.kind | "action" / "script" / "workflow" / "platform_api" | required; Target kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow. |
| data[] (variant 3).data.target.name | string | required; Target name: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| data[] (variant 3).data.target.revision | string | optional; Id (actr_) of the action revision that executed; present only for action calls. |
| data[] (variant 3).data.target.version | string | optional; Exact version that ran; present only for script and workflow calls. |
| data[] (variant 3).data.args_preview | string | required; Single-line preview of the call arguments, truncated on the server; payloads over 32 KB are kept in object storage rather than inline. |
| data[] (variant 3).data.result_preview | null / string | required; Single-line preview of the returned value, truncated on the server; null until the call ends. |
| data[] (variant 3).data.status | "running" / "completed" / "faulted" / "cancelled" | required; Call status. running means still executing; completed means it returned normally; faulted means it failed and error explains why; cancelled means it was stopped because the run was cancelled. |
| data[] (variant 3).data.started_at | string | required; Time the call started (RFC 3339 UTC). |
| data[] (variant 3).data.ended_at | null / string | required; Time the call ended (RFC 3339 UTC), or null while it is running. |
| data[] (variant 3).data.duration_ms | null / number | required; Milliseconds from start to end, or null while the call is running. |
| data[] (variant 3).data.error | null / object | required; Error details when the call failed; null if it succeeded or is still running. |
| data[] (variant 3).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data[] (variant 3).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data[] (variant 3).data.error (variant 2).title | string | required; Short error title. |
| data[] (variant 3).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data[] (variant 3).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data[] (variant 3).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data[] (variant 3).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data[] (variant 3).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data[] (variant 3).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data[] (variant 3).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data[] (variant 3).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data[] (variant 3).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data[] (variant 3).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data[] (variant 3).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data[] (variant 3).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data[] (variant 3).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data[] (variant 3).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 3).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 3).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data[] (variant 3).data.child_run_id | null / string | required; When the target is a script or workflow, the id of the child run this call started; null for action and platform API calls. |
| data[] (variant 3).data.invocation_key | string | required; Key identifying this logical call, sent downstream so that retries under at-least-once delivery can be deduplicated. |
| data[] (variant 3).data.request_id | string / null | required; Downstream response X-Request-Id, or null before a response or when the header is absent. |
| data[] (variant 3).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data[] (variant 3).id | string | required; Event id, unique within the run's ledger. |
| data[] (variant 3).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data[] (variant 3).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data[] (variant 3).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data[] (variant 3).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| data[] (variant 4).type | "ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed" | required; Event type. ai.praxis.automation.task.started means a step started; ai.praxis.automation.task.completed means a step ended; data is the step record. |
| data[] (variant 4).data | object | required; Record of one execution of a workflow step. A loop produces several records for the same step (different iteration) and a retry increments attempt. no additional fields. |
| data[] (variant 4).data.id | string | required; Identifier of this step execution record; treat it as an opaque string. |
| data[] (variant 4).data.run_id | string | required; ID of the owning run. |
| data[] (variant 4).data.reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| data[] (variant 4).data.name | string | required; Step name, the key of the step in the workflow YAML. |
| data[] (variant 4).data.kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| data[] (variant 4).data.iteration | number[] | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| data[] (variant 4).data.attempt | number | required; Attempt number of this execution; it increases when the step is re-executed by a retry. |
| data[] (variant 4).data.status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| data[] (variant 4).data.skipped | boolean | required; true when the step was skipped without actually executing. |
| data[] (variant 4).data.started_at | null / string | required; Time the step started (RFC 3339 UTC), or null. |
| data[] (variant 4).data.ended_at | null / string | required; Time the step ended (RFC 3339 UTC), or null. |
| data[] (variant 4).data.duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| data[] (variant 4).data.input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[] (variant 4).data.input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 4).data.input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 4).data.input_truncated | boolean | required; true when input exceeded 32 KB and was truncated. |
| data[] (variant 4).data.output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[] (variant 4).data.output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 4).data.output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 4).data.output_truncated | boolean | required; True when output is omitted because it exceeds the inline limit. |
| data[] (variant 4).data.error | null / object | required; Error details when the step failed; null otherwise. |
| data[] (variant 4).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data[] (variant 4).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data[] (variant 4).data.error (variant 2).title | string | required; Short error title. |
| data[] (variant 4).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data[] (variant 4).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data[] (variant 4).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data[] (variant 4).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data[] (variant 4).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data[] (variant 4).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data[] (variant 4).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data[] (variant 4).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data[] (variant 4).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data[] (variant 4).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data[] (variant 4).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data[] (variant 4).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data[] (variant 4).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data[] (variant 4).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 4).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 4).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data[] (variant 4).data.action | null / object | required; Action {name, revision} a call step executed; null for other steps. |
| data[] (variant 4).data.action (variant 2).name | string | required; Full action name, ns/name. |
| data[] (variant 4).data.action (variant 2).revision | string | required; Id (actr_) of the action revision that ran. |
| data[] (variant 4).data.child_run | null / object | required; Summary {id, number, status, resolved_version} of the child run a run step started; null for other steps. |
| data[] (variant 4).data.child_run (variant 2).id | string | required; Id (run_) of the child run, readable as soon as it is created. |
| data[] (variant 4).data.child_run (variant 2).number | null / number | required; Sequence number of the child run within its definition; null for ad-hoc runs. |
| data[] (variant 4).data.child_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Status of the child run. pending is not started; running is executing; waiting is waiting; suspended is suspended; cancelled was cancelled; faulted failed; completed succeeded. An awaited child is updated to its terminal status when it ends; a detached child keeps the status at launch. |
| data[] (variant 4).data.child_run (variant 2).resolved_version | null / string | required; Exact version the child run resolved to; null for ad-hoc runs. |
| data[] (variant 4).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data[] (variant 4).id | string | required; Event id, unique within the run's ledger. |
| data[] (variant 4).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data[] (variant 4).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data[] (variant 4).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data[] (variant 4).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| data[] (variant 5).type | "ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved" | required; Event type. ai.praxis.automation.wait.created means a wait point was created; ai.praxis.automation.wait.resolved means it was satisfied, expired or cancelled; data is the wait point. |
| data[] (variant 5).data | object | required; A wait point on a run; the workflow does not continue until it is resolved, expires or is cancelled. no additional fields. |
| data[] (variant 5).data.id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| data[] (variant 5).data.run_id | string | required; Id (run_) of the run this wait belongs to. |
| data[] (variant 5).data.kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| data[] (variant 5).data.state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| data[] (variant 5).data.task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| data[] (variant 5).data.task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| data[] (variant 5).data.task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| data[] (variant 5).data.resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| data[] (variant 5).data.event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| data[] (variant 5).data.child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| data[] (variant 5).data.created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| data[] (variant 5).data.expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| data[] (variant 5).data.resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| data[] (variant 5).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data[] (variant 5).id | string | required; Event id, unique within the run's ledger. |
| data[] (variant 5).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data[] (variant 5).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data[] (variant 5).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data[] (variant 5).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
text/event-stream
| Field | Type | Description |
|---|---|---|
| id | string | optional; Resume cursor of this entry; send it back as Last-Event-ID, or as cursor on the JSON form, to continue after it. Absent on the end event. |
| event | "ai.praxis.automation.run.status" / "ai.praxis.automation.run.progress" / "ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed" / "ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed" / "ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved" / "end" | required; SSE event name: one of ai.praxis.automation.run.status, ai.praxis.automation.run.progress, ai.praxis.automation.call.started, ai.praxis.automation.call.completed, ai.praxis.automation.task.started, ai.praxis.automation.task.completed, ai.praxis.automation.wait.created, ai.praxis.automation.wait.resolved, naming the RunEvent type carried in data; end is sent once when the run has reached a terminal status and closes the stream. |
| data | object / object / object / object / object / object | required; Decoded JSON of one run event, whose shape is selected by its type; for the end event, an empty object. |
| data (variant 1) (variant 1).type | "ai.praxis.automation.run.status" | required; Event type: always ai.praxis.automation.run.status, the run status changed; data is the full run. |
| data (variant 1) (variant 1).data | object | required; Full state of one run: target, status, input and output, error, initiator, position in the run tree and its timestamps. no additional fields. |
| data (variant 1) (variant 1).data.id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| data (variant 1) (variant 1).data.kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data (variant 1) (variant 1).data.number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| data (variant 1) (variant 1).data.definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| data (variant 1) (variant 1).data.definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| data (variant 1) (variant 1).data.definition (variant 2).name | string | required; Name of the script or workflow. |
| data (variant 1) (variant 1).data.target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| data (variant 1) (variant 1).data.resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| data (variant 1) (variant 1).data.source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| data (variant 1) (variant 1).data.language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| data (variant 1) (variant 1).data.status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| data (variant 1) (variant 1).data.progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| data (variant 1) (variant 1).data.progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| data (variant 1) (variant 1).data.progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| data (variant 1) (variant 1).data.progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| data (variant 1) (variant 1).data.progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| data (variant 1) (variant 1).data.current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| data (variant 1) (variant 1).data.current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| data (variant 1) (variant 1).data.current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| data (variant 1) (variant 1).data.current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| data (variant 1) (variant 1).data.current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| data (variant 1) (variant 1).data.current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| data (variant 1) (variant 1).data.current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| data (variant 1) (variant 1).data.current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| data (variant 1) (variant 1).data.current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| data (variant 1) (variant 1).data.current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| data (variant 1) (variant 1).data.current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| data (variant 1) (variant 1).data.current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| data (variant 1) (variant 1).data.current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| data (variant 1) (variant 1).data.current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| data (variant 1) (variant 1).data.counters | object | required; Cumulative counters of a run. no additional fields. |
| data (variant 1) (variant 1).data.counters.calls | number | required; Total number of calls the script made. |
| data (variant 1) (variant 1).data.counters.action_calls | number | required; How many of those calls invoked actions. |
| data (variant 1) (variant 1).data.counters.child_runs | number | required; Number of child runs started. |
| data (variant 1) (variant 1).data.counters.tasks_completed | number | required; Number of workflow steps completed. |
| data (variant 1) (variant 1).data.counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| data (variant 1) (variant 1).data.input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data (variant 1) (variant 1).data.input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data (variant 1) (variant 1).data.input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data (variant 1) (variant 1).data.output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data (variant 1) (variant 1).data.output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data (variant 1) (variant 1).data.output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data (variant 1) (variant 1).data.error | null / object | required; Error details when the run faulted; null otherwise. |
| data (variant 1) (variant 1).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data (variant 1) (variant 1).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data (variant 1) (variant 1).data.error (variant 2).title | string | required; Short error title. |
| data (variant 1) (variant 1).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data (variant 1) (variant 1).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data (variant 1) (variant 1).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data (variant 1) (variant 1).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data (variant 1) (variant 1).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data (variant 1) (variant 1).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data (variant 1) (variant 1).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data (variant 1) (variant 1).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data (variant 1) (variant 1).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data (variant 1) (variant 1).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data (variant 1) (variant 1).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data (variant 1) (variant 1).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data (variant 1) (variant 1).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data (variant 1) (variant 1).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data (variant 1) (variant 1).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data (variant 1) (variant 1).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data (variant 1) (variant 1).data.initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| data (variant 1) (variant 1).data.initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data (variant 1) (variant 1).data.initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data (variant 1) (variant 1).data.channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| data (variant 1) (variant 1).data.owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| data (variant 1) (variant 1).data.parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| data (variant 1) (variant 1).data.parent (variant 2).id | string | required; Id (run_) of the parent run. |
| data (variant 1) (variant 1).data.parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| data (variant 1) (variant 1).data.parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| data (variant 1) (variant 1).data.parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| data (variant 1) (variant 1).data.parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| data (variant 1) (variant 1).data.parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| data (variant 1) (variant 1).data.root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| data (variant 1) (variant 1).data.depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| data (variant 1) (variant 1).data.attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| data (variant 1) (variant 1).data.deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| data (variant 1) (variant 1).data.created_at | string | required; Time the run was created (RFC 3339 UTC). |
| data (variant 1) (variant 1).data.started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| data (variant 1) (variant 1).data.ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| data (variant 1) (variant 1).data.updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| data (variant 1) (variant 1).data.heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| data (variant 1) (variant 1).data.cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| data (variant 1) (variant 1).data.cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| data (variant 1) (variant 1).data.cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data (variant 1) (variant 1).data.cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data (variant 1) (variant 1).data.cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| data (variant 1) (variant 1).data.suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| data (variant 1) (variant 1).data.suspended_by | null / object | required; Principal that requested suspension, or null. |
| data (variant 1) (variant 1).data.suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data (variant 1) (variant 1).data.suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data (variant 1) (variant 1).data.queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| data (variant 1) (variant 1).data.run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| data (variant 1) (variant 1).data.wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| data (variant 1) (variant 1).data.usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| data (variant 1) (variant 1).data.usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| data (variant 1) (variant 1).data.usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| data (variant 1) (variant 1).data.usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| data (variant 1) (variant 1).data.usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| data (variant 1) (variant 1).data.usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| data (variant 1) (variant 1).data.usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| data (variant 1) (variant 1).data.usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| data (variant 1) (variant 1).data.rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| data (variant 1) (variant 1).data.labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| data (variant 1) (variant 1).data.trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| data (variant 1) (variant 1).data.trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| data (variant 1) (variant 1).data.trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| data (variant 1) (variant 1).data.cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| data (variant 1) (variant 1).data.input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| data (variant 1) (variant 1).data.output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
| data (variant 1) (variant 1).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data (variant 1) (variant 1).id | string | required; Event id, unique within the run's ledger. |
| data (variant 1) (variant 1).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data (variant 1) (variant 1).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data (variant 1) (variant 1).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data (variant 1) (variant 1).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| data (variant 1) (variant 2).type | "ai.praxis.automation.run.progress" | required; Event type: always ai.praxis.automation.run.progress, the run reported new progress; data is the progress. |
| data (variant 1) (variant 2).data | object | required; Progress reported by a run: a label, the amount completed and the total. no additional fields. |
| data (variant 1) (variant 2).data.label | string | required; Short progress label, such as the current stage. |
| data (variant 1) (variant 2).data.current | null / number | required; Amount completed so far, or null if not reported. |
| data (variant 1) (variant 2).data.total | null / number | required; Total amount, or null when unknown. |
| data (variant 1) (variant 2).data.updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| data (variant 1) (variant 2).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data (variant 1) (variant 2).id | string | required; Event id, unique within the run's ledger. |
| data (variant 1) (variant 2).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data (variant 1) (variant 2).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data (variant 1) (variant 2).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data (variant 1) (variant 2).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| data (variant 1) (variant 3).type | "ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed" | required; Event type. ai.praxis.automation.call.started means a call started; ai.praxis.automation.call.completed means a call ended, successfully or not; data is the call record. |
| data (variant 1) (variant 3).data | object | required; Record of one call made during a script run (an action, platform API, script or workflow), ordered by seq. no additional fields. |
| data (variant 1) (variant 3).data.id | string | required; Call id, prefixed call_. |
| data (variant 1) (variant 3).data.run_id | string | required; Id (run_) of the script run that made the call. |
| data (variant 1) (variant 3).data.seq | number | required; Position of the call within the run, increasing in call order; together with run_id it locates the call. |
| data (variant 1) (variant 3).data.target | object | required; The target that was called: {kind, name, revision?, version?}. no additional fields. |
| data (variant 1) (variant 3).data.target.kind | "action" / "script" / "workflow" / "platform_api" | required; Target kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow. |
| data (variant 1) (variant 3).data.target.name | string | required; Target name: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| data (variant 1) (variant 3).data.target.revision | string | optional; Id (actr_) of the action revision that executed; present only for action calls. |
| data (variant 1) (variant 3).data.target.version | string | optional; Exact version that ran; present only for script and workflow calls. |
| data (variant 1) (variant 3).data.args_preview | string | required; Single-line preview of the call arguments, truncated on the server; payloads over 32 KB are kept in object storage rather than inline. |
| data (variant 1) (variant 3).data.result_preview | null / string | required; Single-line preview of the returned value, truncated on the server; null until the call ends. |
| data (variant 1) (variant 3).data.status | "running" / "completed" / "faulted" / "cancelled" | required; Call status. running means still executing; completed means it returned normally; faulted means it failed and error explains why; cancelled means it was stopped because the run was cancelled. |
| data (variant 1) (variant 3).data.started_at | string | required; Time the call started (RFC 3339 UTC). |
| data (variant 1) (variant 3).data.ended_at | null / string | required; Time the call ended (RFC 3339 UTC), or null while it is running. |
| data (variant 1) (variant 3).data.duration_ms | null / number | required; Milliseconds from start to end, or null while the call is running. |
| data (variant 1) (variant 3).data.error | null / object | required; Error details when the call failed; null if it succeeded or is still running. |
| data (variant 1) (variant 3).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data (variant 1) (variant 3).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data (variant 1) (variant 3).data.error (variant 2).title | string | required; Short error title. |
| data (variant 1) (variant 3).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data (variant 1) (variant 3).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data (variant 1) (variant 3).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data (variant 1) (variant 3).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data (variant 1) (variant 3).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data (variant 1) (variant 3).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data (variant 1) (variant 3).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data (variant 1) (variant 3).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data (variant 1) (variant 3).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data (variant 1) (variant 3).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data (variant 1) (variant 3).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data (variant 1) (variant 3).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data (variant 1) (variant 3).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data (variant 1) (variant 3).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data (variant 1) (variant 3).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data (variant 1) (variant 3).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data (variant 1) (variant 3).data.child_run_id | null / string | required; When the target is a script or workflow, the id of the child run this call started; null for action and platform API calls. |
| data (variant 1) (variant 3).data.invocation_key | string | required; Key identifying this logical call, sent downstream so that retries under at-least-once delivery can be deduplicated. |
| data (variant 1) (variant 3).data.request_id | string / null | required; Downstream response X-Request-Id, or null before a response or when the header is absent. |
| data (variant 1) (variant 3).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data (variant 1) (variant 3).id | string | required; Event id, unique within the run's ledger. |
| data (variant 1) (variant 3).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data (variant 1) (variant 3).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data (variant 1) (variant 3).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data (variant 1) (variant 3).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| data (variant 1) (variant 4).type | "ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed" | required; Event type. ai.praxis.automation.task.started means a step started; ai.praxis.automation.task.completed means a step ended; data is the step record. |
| data (variant 1) (variant 4).data | object | required; Record of one execution of a workflow step. A loop produces several records for the same step (different iteration) and a retry increments attempt. no additional fields. |
| data (variant 1) (variant 4).data.id | string | required; Identifier of this step execution record; treat it as an opaque string. |
| data (variant 1) (variant 4).data.run_id | string | required; ID of the owning run. |
| data (variant 1) (variant 4).data.reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| data (variant 1) (variant 4).data.name | string | required; Step name, the key of the step in the workflow YAML. |
| data (variant 1) (variant 4).data.kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| data (variant 1) (variant 4).data.iteration | number[] | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| data (variant 1) (variant 4).data.attempt | number | required; Attempt number of this execution; it increases when the step is re-executed by a retry. |
| data (variant 1) (variant 4).data.status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| data (variant 1) (variant 4).data.skipped | boolean | required; true when the step was skipped without actually executing. |
| data (variant 1) (variant 4).data.started_at | null / string | required; Time the step started (RFC 3339 UTC), or null. |
| data (variant 1) (variant 4).data.ended_at | null / string | required; Time the step ended (RFC 3339 UTC), or null. |
| data (variant 1) (variant 4).data.duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| data (variant 1) (variant 4).data.input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data (variant 1) (variant 4).data.input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data (variant 1) (variant 4).data.input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data (variant 1) (variant 4).data.input_truncated | boolean | required; true when input exceeded 32 KB and was truncated. |
| data (variant 1) (variant 4).data.output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data (variant 1) (variant 4).data.output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data (variant 1) (variant 4).data.output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data (variant 1) (variant 4).data.output_truncated | boolean | required; True when output is omitted because it exceeds the inline limit. |
| data (variant 1) (variant 4).data.error | null / object | required; Error details when the step failed; null otherwise. |
| data (variant 1) (variant 4).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data (variant 1) (variant 4).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data (variant 1) (variant 4).data.error (variant 2).title | string | required; Short error title. |
| data (variant 1) (variant 4).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data (variant 1) (variant 4).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data (variant 1) (variant 4).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data (variant 1) (variant 4).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data (variant 1) (variant 4).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data (variant 1) (variant 4).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| data (variant 1) (variant 4).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data (variant 1) (variant 4).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data (variant 1) (variant 4).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data (variant 1) (variant 4).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data (variant 1) (variant 4).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| data (variant 1) (variant 4).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data (variant 1) (variant 4).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data (variant 1) (variant 4).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data (variant 1) (variant 4).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data (variant 1) (variant 4).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data (variant 1) (variant 4).data.action | null / object | required; Action {name, revision} a call step executed; null for other steps. |
| data (variant 1) (variant 4).data.action (variant 2).name | string | required; Full action name, ns/name. |
| data (variant 1) (variant 4).data.action (variant 2).revision | string | required; Id (actr_) of the action revision that ran. |
| data (variant 1) (variant 4).data.child_run | null / object | required; Summary {id, number, status, resolved_version} of the child run a run step started; null for other steps. |
| data (variant 1) (variant 4).data.child_run (variant 2).id | string | required; Id (run_) of the child run, readable as soon as it is created. |
| data (variant 1) (variant 4).data.child_run (variant 2).number | null / number | required; Sequence number of the child run within its definition; null for ad-hoc runs. |
| data (variant 1) (variant 4).data.child_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Status of the child run. pending is not started; running is executing; waiting is waiting; suspended is suspended; cancelled was cancelled; faulted failed; completed succeeded. An awaited child is updated to its terminal status when it ends; a detached child keeps the status at launch. |
| data (variant 1) (variant 4).data.child_run (variant 2).resolved_version | null / string | required; Exact version the child run resolved to; null for ad-hoc runs. |
| data (variant 1) (variant 4).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data (variant 1) (variant 4).id | string | required; Event id, unique within the run's ledger. |
| data (variant 1) (variant 4).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data (variant 1) (variant 4).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data (variant 1) (variant 4).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data (variant 1) (variant 4).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| data (variant 1) (variant 5).type | "ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved" | required; Event type. ai.praxis.automation.wait.created means a wait point was created; ai.praxis.automation.wait.resolved means it was satisfied, expired or cancelled; data is the wait point. |
| data (variant 1) (variant 5).data | object | required; A wait point on a run; the workflow does not continue until it is resolved, expires or is cancelled. no additional fields. |
| data (variant 1) (variant 5).data.id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| data (variant 1) (variant 5).data.run_id | string | required; Id (run_) of the run this wait belongs to. |
| data (variant 1) (variant 5).data.kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| data (variant 1) (variant 5).data.state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| data (variant 1) (variant 5).data.task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| data (variant 1) (variant 5).data.task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| data (variant 1) (variant 5).data.task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| data (variant 1) (variant 5).data.resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| data (variant 1) (variant 5).data.event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| data (variant 1) (variant 5).data.child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| data (variant 1) (variant 5).data.created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| data (variant 1) (variant 5).data.expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| data (variant 1) (variant 5).data.resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| data (variant 1) (variant 5).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| data (variant 1) (variant 5).id | string | required; Event id, unique within the run's ledger. |
| data (variant 1) (variant 5).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| data (variant 1) (variant 5).time | string | required; Time the event occurred (RFC 3339 UTC). |
| data (variant 1) (variant 5).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data (variant 1) (variant 5).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| (variant 1).event | "ai.praxis.automation.run.status" / "ai.praxis.automation.run.progress" / "ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed" / "ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed" / "ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved" | optional; SSE event name: one of ai.praxis.automation.run.status, ai.praxis.automation.run.progress, ai.praxis.automation.call.started, ai.praxis.automation.call.completed, ai.praxis.automation.task.started, ai.praxis.automation.task.completed, ai.praxis.automation.wait.created, ai.praxis.automation.wait.resolved, naming the RunEvent type carried in data. |
| (variant 1).data | object / object / object / object / object | optional; One CloudEvents entry in a run's ledger; the payload carries the full projection so no re-fetch is needed. type decides the shape of data: run.status carries a run, run.progress a progress, call.* a call, task.* a step and wait.* a wait point. |
| (variant 1).data (variant 1).type | "ai.praxis.automation.run.status" | required; Event type: always ai.praxis.automation.run.status, the run status changed; data is the full run. |
| (variant 1).data (variant 1).data | object | required; Full state of one run: target, status, input and output, error, initiator, position in the run tree and its timestamps. no additional fields. |
| (variant 1).data (variant 1).data.id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| (variant 1).data (variant 1).data.kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| (variant 1).data (variant 1).data.number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| (variant 1).data (variant 1).data.definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| (variant 1).data (variant 1).data.definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| (variant 1).data (variant 1).data.definition (variant 2).name | string | required; Name of the script or workflow. |
| (variant 1).data (variant 1).data.target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| (variant 1).data (variant 1).data.resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| (variant 1).data (variant 1).data.source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| (variant 1).data (variant 1).data.language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| (variant 1).data (variant 1).data.status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| (variant 1).data (variant 1).data.progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| (variant 1).data (variant 1).data.progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| (variant 1).data (variant 1).data.progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| (variant 1).data (variant 1).data.progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| (variant 1).data (variant 1).data.progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| (variant 1).data (variant 1).data.current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| (variant 1).data (variant 1).data.current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| (variant 1).data (variant 1).data.current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| (variant 1).data (variant 1).data.current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| (variant 1).data (variant 1).data.current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| (variant 1).data (variant 1).data.current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| (variant 1).data (variant 1).data.current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| (variant 1).data (variant 1).data.current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| (variant 1).data (variant 1).data.current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| (variant 1).data (variant 1).data.current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| (variant 1).data (variant 1).data.current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| (variant 1).data (variant 1).data.current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| (variant 1).data (variant 1).data.current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| (variant 1).data (variant 1).data.current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| (variant 1).data (variant 1).data.counters | object | required; Cumulative counters of a run. no additional fields. |
| (variant 1).data (variant 1).data.counters.calls | number | required; Total number of calls the script made. |
| (variant 1).data (variant 1).data.counters.action_calls | number | required; How many of those calls invoked actions. |
| (variant 1).data (variant 1).data.counters.child_runs | number | required; Number of child runs started. |
| (variant 1).data (variant 1).data.counters.tasks_completed | number | required; Number of workflow steps completed. |
| (variant 1).data (variant 1).data.counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| (variant 1).data (variant 1).data.input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| (variant 1).data (variant 1).data.input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).data (variant 1).data.input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).data (variant 1).data.output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| (variant 1).data (variant 1).data.output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).data (variant 1).data.output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).data (variant 1).data.error | null / object | required; Error details when the run faulted; null otherwise. |
| (variant 1).data (variant 1).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| (variant 1).data (variant 1).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| (variant 1).data (variant 1).data.error (variant 2).title | string | required; Short error title. |
| (variant 1).data (variant 1).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| (variant 1).data (variant 1).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| (variant 1).data (variant 1).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| (variant 1).data (variant 1).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| (variant 1).data (variant 1).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| (variant 1).data (variant 1).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| (variant 1).data (variant 1).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| (variant 1).data (variant 1).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| (variant 1).data (variant 1).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| (variant 1).data (variant 1).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| (variant 1).data (variant 1).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| (variant 1).data (variant 1).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| (variant 1).data (variant 1).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| (variant 1).data (variant 1).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| (variant 1).data (variant 1).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| (variant 1).data (variant 1).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| (variant 1).data (variant 1).data.initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| (variant 1).data (variant 1).data.initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| (variant 1).data (variant 1).data.initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| (variant 1).data (variant 1).data.channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| (variant 1).data (variant 1).data.owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| (variant 1).data (variant 1).data.parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| (variant 1).data (variant 1).data.parent (variant 2).id | string | required; Id (run_) of the parent run. |
| (variant 1).data (variant 1).data.parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| (variant 1).data (variant 1).data.parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| (variant 1).data (variant 1).data.parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| (variant 1).data (variant 1).data.parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| (variant 1).data (variant 1).data.parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| (variant 1).data (variant 1).data.root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| (variant 1).data (variant 1).data.depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| (variant 1).data (variant 1).data.attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| (variant 1).data (variant 1).data.deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| (variant 1).data (variant 1).data.created_at | string | required; Time the run was created (RFC 3339 UTC). |
| (variant 1).data (variant 1).data.started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| (variant 1).data (variant 1).data.ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| (variant 1).data (variant 1).data.updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| (variant 1).data (variant 1).data.heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| (variant 1).data (variant 1).data.cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| (variant 1).data (variant 1).data.cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| (variant 1).data (variant 1).data.cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| (variant 1).data (variant 1).data.cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| (variant 1).data (variant 1).data.cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| (variant 1).data (variant 1).data.suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| (variant 1).data (variant 1).data.suspended_by | null / object | required; Principal that requested suspension, or null. |
| (variant 1).data (variant 1).data.suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| (variant 1).data (variant 1).data.suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| (variant 1).data (variant 1).data.queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| (variant 1).data (variant 1).data.run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| (variant 1).data (variant 1).data.wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| (variant 1).data (variant 1).data.usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| (variant 1).data (variant 1).data.usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| (variant 1).data (variant 1).data.usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| (variant 1).data (variant 1).data.usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| (variant 1).data (variant 1).data.usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| (variant 1).data (variant 1).data.usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| (variant 1).data (variant 1).data.usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| (variant 1).data (variant 1).data.usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| (variant 1).data (variant 1).data.rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| (variant 1).data (variant 1).data.labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| (variant 1).data (variant 1).data.trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| (variant 1).data (variant 1).data.trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| (variant 1).data (variant 1).data.trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| (variant 1).data (variant 1).data.cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| (variant 1).data (variant 1).data.input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| (variant 1).data (variant 1).data.output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
| (variant 1).data (variant 1).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| (variant 1).data (variant 1).id | string | required; Event id, unique within the run's ledger. |
| (variant 1).data (variant 1).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| (variant 1).data (variant 1).time | string | required; Time the event occurred (RFC 3339 UTC). |
| (variant 1).data (variant 1).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| (variant 1).data (variant 1).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| (variant 1).data (variant 2).type | "ai.praxis.automation.run.progress" | required; Event type: always ai.praxis.automation.run.progress, the run reported new progress; data is the progress. |
| (variant 1).data (variant 2).data | object | required; Progress reported by a run: a label, the amount completed and the total. no additional fields. |
| (variant 1).data (variant 2).data.label | string | required; Short progress label, such as the current stage. |
| (variant 1).data (variant 2).data.current | null / number | required; Amount completed so far, or null if not reported. |
| (variant 1).data (variant 2).data.total | null / number | required; Total amount, or null when unknown. |
| (variant 1).data (variant 2).data.updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| (variant 1).data (variant 2).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| (variant 1).data (variant 2).id | string | required; Event id, unique within the run's ledger. |
| (variant 1).data (variant 2).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| (variant 1).data (variant 2).time | string | required; Time the event occurred (RFC 3339 UTC). |
| (variant 1).data (variant 2).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| (variant 1).data (variant 2).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| (variant 1).data (variant 3).type | "ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed" | required; Event type. ai.praxis.automation.call.started means a call started; ai.praxis.automation.call.completed means a call ended, successfully or not; data is the call record. |
| (variant 1).data (variant 3).data | object | required; Record of one call made during a script run (an action, platform API, script or workflow), ordered by seq. no additional fields. |
| (variant 1).data (variant 3).data.id | string | required; Call id, prefixed call_. |
| (variant 1).data (variant 3).data.run_id | string | required; Id (run_) of the script run that made the call. |
| (variant 1).data (variant 3).data.seq | number | required; Position of the call within the run, increasing in call order; together with run_id it locates the call. |
| (variant 1).data (variant 3).data.target | object | required; The target that was called: {kind, name, revision?, version?}. no additional fields. |
| (variant 1).data (variant 3).data.target.kind | "action" / "script" / "workflow" / "platform_api" | required; Target kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow. |
| (variant 1).data (variant 3).data.target.name | string | required; Target name: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| (variant 1).data (variant 3).data.target.revision | string | optional; Id (actr_) of the action revision that executed; present only for action calls. |
| (variant 1).data (variant 3).data.target.version | string | optional; Exact version that ran; present only for script and workflow calls. |
| (variant 1).data (variant 3).data.args_preview | string | required; Single-line preview of the call arguments, truncated on the server; payloads over 32 KB are kept in object storage rather than inline. |
| (variant 1).data (variant 3).data.result_preview | null / string | required; Single-line preview of the returned value, truncated on the server; null until the call ends. |
| (variant 1).data (variant 3).data.status | "running" / "completed" / "faulted" / "cancelled" | required; Call status. running means still executing; completed means it returned normally; faulted means it failed and error explains why; cancelled means it was stopped because the run was cancelled. |
| (variant 1).data (variant 3).data.started_at | string | required; Time the call started (RFC 3339 UTC). |
| (variant 1).data (variant 3).data.ended_at | null / string | required; Time the call ended (RFC 3339 UTC), or null while it is running. |
| (variant 1).data (variant 3).data.duration_ms | null / number | required; Milliseconds from start to end, or null while the call is running. |
| (variant 1).data (variant 3).data.error | null / object | required; Error details when the call failed; null if it succeeded or is still running. |
| (variant 1).data (variant 3).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| (variant 1).data (variant 3).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| (variant 1).data (variant 3).data.error (variant 2).title | string | required; Short error title. |
| (variant 1).data (variant 3).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| (variant 1).data (variant 3).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| (variant 1).data (variant 3).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| (variant 1).data (variant 3).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| (variant 1).data (variant 3).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| (variant 1).data (variant 3).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| (variant 1).data (variant 3).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| (variant 1).data (variant 3).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| (variant 1).data (variant 3).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| (variant 1).data (variant 3).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| (variant 1).data (variant 3).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| (variant 1).data (variant 3).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| (variant 1).data (variant 3).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| (variant 1).data (variant 3).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| (variant 1).data (variant 3).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| (variant 1).data (variant 3).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| (variant 1).data (variant 3).data.child_run_id | null / string | required; When the target is a script or workflow, the id of the child run this call started; null for action and platform API calls. |
| (variant 1).data (variant 3).data.invocation_key | string | required; Key identifying this logical call, sent downstream so that retries under at-least-once delivery can be deduplicated. |
| (variant 1).data (variant 3).data.request_id | string / null | required; Downstream response X-Request-Id, or null before a response or when the header is absent. |
| (variant 1).data (variant 3).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| (variant 1).data (variant 3).id | string | required; Event id, unique within the run's ledger. |
| (variant 1).data (variant 3).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| (variant 1).data (variant 3).time | string | required; Time the event occurred (RFC 3339 UTC). |
| (variant 1).data (variant 3).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| (variant 1).data (variant 3).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| (variant 1).data (variant 4).type | "ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed" | required; Event type. ai.praxis.automation.task.started means a step started; ai.praxis.automation.task.completed means a step ended; data is the step record. |
| (variant 1).data (variant 4).data | object | required; Record of one execution of a workflow step. A loop produces several records for the same step (different iteration) and a retry increments attempt. no additional fields. |
| (variant 1).data (variant 4).data.id | string | required; Identifier of this step execution record; treat it as an opaque string. |
| (variant 1).data (variant 4).data.run_id | string | required; ID of the owning run. |
| (variant 1).data (variant 4).data.reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| (variant 1).data (variant 4).data.name | string | required; Step name, the key of the step in the workflow YAML. |
| (variant 1).data (variant 4).data.kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| (variant 1).data (variant 4).data.iteration | number[] | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| (variant 1).data (variant 4).data.attempt | number | required; Attempt number of this execution; it increases when the step is re-executed by a retry. |
| (variant 1).data (variant 4).data.status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| (variant 1).data (variant 4).data.skipped | boolean | required; true when the step was skipped without actually executing. |
| (variant 1).data (variant 4).data.started_at | null / string | required; Time the step started (RFC 3339 UTC), or null. |
| (variant 1).data (variant 4).data.ended_at | null / string | required; Time the step ended (RFC 3339 UTC), or null. |
| (variant 1).data (variant 4).data.duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| (variant 1).data (variant 4).data.input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| (variant 1).data (variant 4).data.input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).data (variant 4).data.input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).data (variant 4).data.input_truncated | boolean | required; true when input exceeded 32 KB and was truncated. |
| (variant 1).data (variant 4).data.output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| (variant 1).data (variant 4).data.output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).data (variant 4).data.output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 1).data (variant 4).data.output_truncated | boolean | required; True when output is omitted because it exceeds the inline limit. |
| (variant 1).data (variant 4).data.error | null / object | required; Error details when the step failed; null otherwise. |
| (variant 1).data (variant 4).data.error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| (variant 1).data (variant 4).data.error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| (variant 1).data (variant 4).data.error (variant 2).title | string | required; Short error title. |
| (variant 1).data (variant 4).data.error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| (variant 1).data (variant 4).data.error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| (variant 1).data (variant 4).data.error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| (variant 1).data (variant 4).data.error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| (variant 1).data (variant 4).data.error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| (variant 1).data (variant 4).data.error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| (variant 1).data (variant 4).data.error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| (variant 1).data (variant 4).data.error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| (variant 1).data (variant 4).data.error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| (variant 1).data (variant 4).data.error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| (variant 1).data (variant 4).data.error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| (variant 1).data (variant 4).data.error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| (variant 1).data (variant 4).data.error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| (variant 1).data (variant 4).data.error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| (variant 1).data (variant 4).data.error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| (variant 1).data (variant 4).data.error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| (variant 1).data (variant 4).data.action | null / object | required; Action {name, revision} a call step executed; null for other steps. |
| (variant 1).data (variant 4).data.action (variant 2).name | string | required; Full action name, ns/name. |
| (variant 1).data (variant 4).data.action (variant 2).revision | string | required; Id (actr_) of the action revision that ran. |
| (variant 1).data (variant 4).data.child_run | null / object | required; Summary {id, number, status, resolved_version} of the child run a run step started; null for other steps. |
| (variant 1).data (variant 4).data.child_run (variant 2).id | string | required; Id (run_) of the child run, readable as soon as it is created. |
| (variant 1).data (variant 4).data.child_run (variant 2).number | null / number | required; Sequence number of the child run within its definition; null for ad-hoc runs. |
| (variant 1).data (variant 4).data.child_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Status of the child run. pending is not started; running is executing; waiting is waiting; suspended is suspended; cancelled was cancelled; faulted failed; completed succeeded. An awaited child is updated to its terminal status when it ends; a detached child keeps the status at launch. |
| (variant 1).data (variant 4).data.child_run (variant 2).resolved_version | null / string | required; Exact version the child run resolved to; null for ad-hoc runs. |
| (variant 1).data (variant 4).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| (variant 1).data (variant 4).id | string | required; Event id, unique within the run's ledger. |
| (variant 1).data (variant 4).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| (variant 1).data (variant 4).time | string | required; Time the event occurred (RFC 3339 UTC). |
| (variant 1).data (variant 4).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| (variant 1).data (variant 4).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| (variant 1).data (variant 5).type | "ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved" | required; Event type. ai.praxis.automation.wait.created means a wait point was created; ai.praxis.automation.wait.resolved means it was satisfied, expired or cancelled; data is the wait point. |
| (variant 1).data (variant 5).data | object | required; A wait point on a run; the workflow does not continue until it is resolved, expires or is cancelled. no additional fields. |
| (variant 1).data (variant 5).data.id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| (variant 1).data (variant 5).data.run_id | string | required; Id (run_) of the run this wait belongs to. |
| (variant 1).data (variant 5).data.kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| (variant 1).data (variant 5).data.state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| (variant 1).data (variant 5).data.task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| (variant 1).data (variant 5).data.task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| (variant 1).data (variant 5).data.task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| (variant 1).data (variant 5).data.resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| (variant 1).data (variant 5).data.event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| (variant 1).data (variant 5).data.child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| (variant 1).data (variant 5).data.created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| (variant 1).data (variant 5).data.expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| (variant 1).data (variant 5).data.resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| (variant 1).data (variant 5).specversion | "1.0" | required; CloudEvents specification version, always 1.0. |
| (variant 1).data (variant 5).id | string | required; Event id, unique within the run's ledger. |
| (variant 1).data (variant 5).source | string | required; Event source, of the form /automation/v1/runs/{id}. |
| (variant 1).data (variant 5).time | string | required; Time the event occurred (RFC 3339 UTC). |
| (variant 1).data (variant 5).cursor | string | required; Event cursor; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| (variant 1).data (variant 5).seq | number | required; Position of the event in the run's ledger, strictly increasing. |
| (variant 2).event | "end" | optional; SSE event name end: sent once when the run has reached a terminal status, and the stream then closes. |
| (variant 2).data | object | optional; Always an empty object for the end event. |
HTTP 200
id: WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwxXQ==
event: ai.praxis.automation.run.status
data: {"type":"ai.praxis.automation.run.status","data":{"id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","kind":"script","number":null,"definition":null,"target":null,"resolved_version":null,"source_digest":"7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d","language":"ts","status":"pending","progress":null,"current_wait":null,"counters":{"calls":0,"action_calls":0,"child_runs":0,"tasks_completed":0,"tasks_total":null},"input":{"n":41},"output":null,"error":null,"initiator":{"type":"api_key","id":"key_3e00b8984967"},"channel":"api","owner":"tnt_3a9759864ccb4e00","trigger":null,"parent":null,"parent_run_id":null,"root_run_id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","depth":0,"attach":null,"deadline_at":"2026-10-13T05:02:40.954Z","created_at":"2026-10-13T04:57:40.954Z","started_at":null,"ended_at":null,"updated_at":"2026-10-13T04:57:40.954Z","heartbeat_at":null,"cancel_requested_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_message":null,"suspend_requested_at":null,"suspended_by":null,"queued_ms":null,"run_ms":null,"wait_ms":null,"usage":null,"rerun_of":null,"labels":{"namespace":"docs-samples","name":"sample-run-1791867412840-b05e8a"}},"specversion":"1.0","id":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwxXQ==","cursor":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwxXQ==","seq":1,"source":"/automation/v1/runs/run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","time":"2026-10-13T04:57:40.954Z"}
id: WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwyXQ==
event: ai.praxis.automation.run.status
data: {"type":"ai.praxis.automation.run.status","data":{"id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","kind":"script","number":null,"definition":null,"target":null,"resolved_version":null,"source_digest":"7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d","language":"ts","status":"running","progress":null,"current_wait":null,"counters":{"calls":0,"action_calls":0,"child_runs":0,"tasks_completed":0,"tasks_total":null},"input":{"n":41},"output":null,"error":null,"initiator":{"type":"api_key","id":"key_3e00b8984967"},"channel":"api","owner":"tnt_3a9759864ccb4e00","trigger":null,"parent":null,"parent_run_id":null,"root_run_id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","depth":0,"attach":null,"deadline_at":"2026-10-13T05:02:40.954Z","created_at":"2026-10-13T04:57:40.954Z","started_at":"2026-10-13T04:57:42.283Z","ended_at":null,"updated_at":"2026-10-13T04:57:42.283Z","heartbeat_at":"2026-10-13T04:57:42.283Z","cancel_requested_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_message":null,"suspend_requested_at":null,"suspended_by":null,"queued_ms":1329,"run_ms":null,"wait_ms":null,"usage":null,"rerun_of":null,"labels":{"namespace":"docs-samples","name":"sample-run-1791867412840-b05e8a"}},"specversion":"1.0","id":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwyXQ==","cursor":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwyXQ==","seq":2,"source":"/automation/v1/runs/run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","time":"2026-10-13T04:57:42.283Z"}
id: WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwzXQ==
event: ai.praxis.automation.run.status
data: {"type":"ai.praxis.automation.run.status","data":{"id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","kind":"script","number":null,"definition":null,"target":null,"resolved_version":null,"source_digest":"7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d","language":"ts","status":"completed","progress":null,"current_wait":null,"counters":{"calls":0,"action_calls":0,"child_runs":0,"tasks_completed":0,"tasks_total":null},"input":{"n":41},"output":{"answer":42},"error":null,"initiator":{"type":"api_key","id":"key_3e00b8984967"},"channel":"api","owner":"tnt_3a9759864ccb4e00","trigger":null,"parent":null,"parent_run_id":null,"root_run_id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","depth":0,"attach":null,"deadline_at":"2026-10-13T05:02:40.954Z","created_at":"2026-10-13T04:57:40.954Z","started_at":"2026-10-13T04:57:42.283Z","ended_at":"2026-10-13T04:57:42.367Z","updated_at":"2026-10-13T04:57:42.367Z","heartbeat_at":"2026-10-13T04:57:42.283Z","cancel_requested_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_message":null,"suspend_requested_at":null,"suspended_by":null,"queued_ms":1329,"run_ms":84,"wait_ms":null,"usage":null,"rerun_of":null,"labels":{"namespace":"docs-samples","name":"sample-run-1791867412840-b05e8a"}},"specversion":"1.0","id":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwzXQ==","cursor":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwzXQ==","seq":3,"source":"/automation/v1/runs/run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","time":"2026-10-13T04:57:42.367Z"}
event: end
data: {}
| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Return a log page within the 30-day retention window by default. Accept: text/event-stream opens a live stream using event: log; id is the resume cursor and Last-Event-ID takes precedence over cursor. : ping arrives every 20 seconds and event: end closes the stream after a terminal run.
GET /automation/v1/runs/{id}/logs
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: limit | integer | optional; Run ledger page size: integer 1–200, default 50; other collections are capped at 100. minimum: 1; maximum: 200 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| header: Accept | "application/json" / "text/event-stream" | optional; application/json (default) reads a ledger page; text/event-stream subscribes to the live stream. |
| header: Last-Event-ID | string | optional; SSE resume cursor; read entries after this event. Takes precedence over cursor and applies only to streams. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/logs" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Accept: text/event-stream"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
for await (const event of automation.runs.logs({
"path": {
"id": env("RUN_ID")
}
})) {
console.log(event);
}Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Log lines (LogLine) on this page, in time order. |
| data[].cursor | string | required; Cursor of this line; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data[].ts | string | required; Time the line was logged (RFC 3339 UTC). |
| data[].level | "debug" / "info" / "warn" / "error" | required; Log level. debug is diagnostic detail; info is general information; warn is a warning; error is an error. |
| data[].message | string | required; Log message text. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
text/event-stream
| Field | Type | Description |
|---|---|---|
| id | string | optional; Resume cursor of this entry; send it back as Last-Event-ID, or as cursor on the JSON form, to continue after it. Absent on the end event. |
| event | "log" / "end" | required; SSE event name: log carries one log line in data; end is sent once when the run has reached a terminal status and closes the stream. |
| data | object / object | required; Decoded JSON of one log line; for the end event, an empty object. |
| data (variant 1).cursor | string | required; Cursor of this line; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| data (variant 1).ts | string | required; Time the line was logged (RFC 3339 UTC). |
| data (variant 1).level | "debug" / "info" / "warn" / "error" | required; Log level. debug is diagnostic detail; info is general information; warn is a warning; error is an error. |
| data (variant 1).message | string | required; Log message text. |
| (variant 1).event | "log" | optional; SSE event name: log, one log line is carried in data. |
| (variant 1).data | object | optional; One log line produced by a run, retained for 30 days. no additional fields. |
| (variant 1).data.cursor | string | required; Cursor of this line; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| (variant 1).data.ts | string | required; Time the line was logged (RFC 3339 UTC). |
| (variant 1).data.level | "debug" / "info" / "warn" / "error" | required; Log level. debug is diagnostic detail; info is general information; warn is a warning; error is an error. |
| (variant 1).data.message | string | required; Log message text. |
| (variant 2).event | "end" | optional; SSE event name end: sent once when the run has reached a terminal status, and the stream then closes. |
| (variant 2).data | object | optional; Always an empty object for the end event. |
HTTP 200
event: end
data: {}
| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read the source and digest used by the run. Results include the language and SHA-256 digest, for both ad hoc and published-definition runs.
GET /automation/v1/runs/{id}/source
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/source" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.runs.retrieveSource({
"path": {
"id": env("RUN_ID")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| source | string | required; Full source (ts or yaml) the run used. |
| sha256 | string | required; SHA-256 digest of the source; usable as expected_source_sha256 when publishing. |
HTTP 200
{
"language": "ts",
"source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
"sha256": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Page through tenant triggers by target, kind and state. ns/name matches all tags or versions of that target; ns/name@spec matches exactly.
GET /automation/v1/triggers
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| query: limit | integer | optional; Page size: integer 1–100, default 25. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: target | string[] | optional; ns/name matches all versions or tags of a target; ns/name@spec matches the stored reference exactly. Separate multiple values with commas to match any value. minItems: 1 |
| query: kind | "schedule" / "webhook"[] | optional; schedule or webhook; omit for both. Separate multiple values with commas to match any value. minItems: 1 |
| query: state | "enabled" / "paused" / "expired"[] | optional; Trigger state: enabled, paused or expired; omit for all. Separate multiple values with commas to match any value. minItems: 1 |
| query: labels | object | optional; Filter using labels[k]=v; comma-separated values for one key match any, and different keys match together. |
| query: created_at[gte] | string | optional; Inclusive creation-time lower bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
| query: created_at[lte] | string | optional; Inclusive creation-time upper bound, as an ISO 8601 timestamp with timezone. format: "date-time" |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TARGET | Published docs-samples/name@1.0.0 |
: "${TARGET:?Set TARGET}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/triggers" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
--get \
--data-urlencode "target=${TARGET}"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.list({
"query": {
"target": [
env("TARGET")
]
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Triggers on this page, ordered by created_at descending, then id descending. |
| data[].name | string | required; Trigger name, 1–100 characters. minLength: 1; maxLength: 100 |
| data[].description | string | required; Trigger description, at most 1000 characters. maxLength: 1000 |
| data[].labels | object | required; Trigger tags as string key and value pairs, at most 64; keys must not start with the reserved prefix praxis. (400 INPUT_INVALID). |
| data[].target | string | required; Script or workflow to run, as ns/name@tag-or-version; it follows latest by default, and @1.2.0 pins a version. |
| data[].input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[].input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[].kind | "schedule" / "webhook" | required; Trigger kind. schedule fires on a plan (cron, every or at); webhook fires on an inbound HTTP request. |
| data[].schedule | object / object / object / null | required; Schedule rule for kind=schedule, exactly one of cron, every or at; null for webhooks. |
| data[].schedule (variant 1) (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| data[].schedule (variant 1) (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| data[].schedule (variant 1) (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| data[].schedule (variant 1) (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| data[].schedule (variant 1) (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| data[].schedule (variant 1) (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| data[].schedule (variant 1) (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| data[].schedule (variant 1) (variant 3).at | string | required; Instant of a one-time firing (RFC 3339 UTC); it cannot be in the past or more than one year ahead. The trigger becomes expired after it runs. format: "date-time" |
| data[].timezone | string | required; IANA time zone name used to interpret the schedule; UTC by default through the API. default: "UTC" |
| data[].start_at | string / null | required; Start time of a scheduled trigger (RFC 3339 UTC); it does not fire before then. null for no limit. |
| data[].end_at | string / null | required; End time of a scheduled trigger (RFC 3339 UTC); after it the trigger becomes expired. null for no end. |
| data[].overlap | "skip" / "allow" | required; Overlap policy when a firing is due while the previous run is still active: skip (default) skips it, allow starts it anyway. default: "skip" |
| data[].catchup_window_seconds | integer | required; Catch-up window in seconds, default 300, for scheduled triggers only: if a firing is later than this (downtime, pause) it is recorded as missed and not run. default: 300; minimum: 0 |
| data[].webhook | object / null | required; Webhook settings for kind=webhook; null for scheduled triggers. |
| data[].webhook (variant 1).input_mode | "body" / "envelope" | required; Shape of the input a webhook delivery gives the target. body (default) passes only the request body; envelope passes an object with body, raw_body, raw_body_encoding, headers, webhook_id and received_at. |
| data[].webhook (variant 1).url_hint | string | required; Masked webhook address with an ellipsis replacing the secret token; it cannot be invoked. Newly created triggers use a full public URL; historical records may contain a relative /automation/v1/hooks/{id}/… path. |
| data[].id | string | required; Trigger id, prefixed trg_; used in the webhook address and by every trigger endpoint. |
| data[].owner | string | required; Tenant that owns the trigger, injected by the gateway; treat it as an opaque string. |
| data[].state | "enabled" / "paused" / "expired" | required; Trigger state. enabled fires on schedule or request; paused does not fire; expired is final, reached after a one-time trigger has run or end_at has passed, and no longer fires. |
| data[].source | "api" / "definition" | required; Origin of the trigger. api was created through the API and can be changed and deleted; definition was generated from the schedule in a workflow YAML and can only be paused or resumed, changes return 409 TRIGGER_MANAGED. |
| data[].created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| data[].created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| data[].created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| data[].created_by_user_id | string | required; Real user id of the creator, forwarded by the gateway; runs the trigger starts take their token from this user, for audit and usage attribution. |
| data[].next_fire_times | string[] | required; Up to the next 5 firing times (RFC 3339 UTC); empty for webhook, paused or expired triggers. maxItems: 5 |
| data[].last_firing | object / null | required; The most recent firing record, or null if it has never fired. |
| data[].last_firing (variant 1).id | string | required; Firing record id; records are kept for 30 days. |
| data[].last_firing (variant 1).trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| data[].last_firing (variant 1).scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| data[].last_firing (variant 1).fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| data[].last_firing (variant 1).outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| data[].last_firing (variant 1).run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| data[].last_firing (variant 1).resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| data[].last_firing (variant 1).error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| data[].last_firing (variant 1).error (variant 1).code | string | required; Error code of the failure. |
| data[].last_firing (variant 1).error (variant 1).message | string | required; Message describing the failure. |
| data[].counts | object | required; Cumulative firing counts {started, skipped, missed, failed}. no additional fields. |
| data[].counts.started | integer | required; Number of firings that started a run. minimum: 0 |
| data[].counts.skipped | integer | required; Number of firings skipped because overlap is skip and the previous run was still active. minimum: 0 |
| data[].counts.missed | integer | required; Number of firings missed because they were later than the catch-up window. minimum: 0 |
| data[].counts.failed | integer | required; Number of firings where creating the run failed. minimum: 0 |
| data[].created_at | string | required; Creation time (RFC 3339 UTC). format: "date-time" |
| data[].updated_at | string | required; Time of the last update (RFC 3339 UTC). format: "date-time" |
| data[].etag | string | required; Current revision tag of the trigger; send it as If-Match when updating, and a mismatch returns 412. |
| data[].usage_30d | object / null | optional; Returned only by GET /triggers/{id}, omitted from lists. Attributed charges over the preceding 30 days for this trigger's runs and descendants. Runs themselves are free; these are actual charges for capabilities such as models and search called during runs, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| data[].usage_30d (variant 1).currency | "USD" | required; Charge currency, always USD. |
| data[].usage_30d (variant 1).cost | string | required; Rated actual charges as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| data[].usage_30d (variant 1).pending_events | integer | required; Number of unrated usage events whose charges will be included later. minimum: 0 |
| next_cursor | string / null | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"owner": "tnt_3a9759864ccb4e00",
"name": "sample-webhook-1791867412840-b05e8a",
"description": "",
"labels": {
"namespace": "docs-samples"
},
"target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
"input": {},
"kind": "webhook",
"schedule": null,
"timezone": "UTC",
"start_at": null,
"end_at": null,
"overlap": "skip",
"catchup_window_seconds": 300,
"webhook": {
"input_mode": "body",
"url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
},
"state": "paused",
"source": "api",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"created_by_user_id": "usr_49d4fcb99517",
"next_fire_times": [],
"last_firing": null,
"counts": {
"started": 0,
"skipped": 0,
"missed": 0,
"failed": 0
},
"created_at": "2026-10-13T04:58:09.974Z",
"updated_at": "2026-10-13T04:58:12.519Z",
"etag": "etag_00mv67n1yf40e7b8d39ce5459d9ce835bfb1083701"
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Schedule recurring or one-time runs, or start runs from a webhook, for a published script or workflow. For one immediate run without a persistent trigger, use praxis.automation.runs.create. There may be at most 100 enabled triggers per tenant. Targets accept only exact versions or tags; webhook_url is returned only when creating a webhook or rotating its URL, so save it securely.
POST /automation/v1/triggers
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
no additional fields.
| Field | Type | Description |
|---|---|---|
| name | string | required; Trigger display name, 1–100 characters and not all whitespace; uniqueness is not required. minLength: 1; maxLength: 100 |
| description | string | optional; Description, at most 1,000 characters. maxLength: 1000 |
| labels | object | optional; At most 64 user labels; the praxis. prefix is reserved and internal labels do not count. Keys 1–40 characters, values at most 500. |
| target | string | required; ns/name@tag or ns/name@version, defaulting to latest when @ is omitted. Triggers do not accept version ranges. |
| input | null / string / number / boolean / object / null / string / number / boolean / object / JSON[][] | optional; Static JSON input for scheduled firings, default {}; checked against the target schema on create/update. Omitted webhook input is not validated at creation. |
| input (variant 5).* (variant 5) | object | Recursive JSON value. |
| input (variant 5).* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| kind | "schedule" / "webhook" | required; schedule fires on a schedule; webhook fires on an HTTP delivery. Immutable after creation. |
| schedule | object / object / object | optional; Choose one: a five-field cron (L/W/# supported), every as an ISO 8601 duration or duration object resolving to positive integer milliseconds from one minute to 366 days, or at as a one-time RFC 3339 timestamp within the next year. |
| schedule (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| schedule (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| schedule (variant 3).at | string | required; One-time firing instant with a Z or ±HH:MM timezone, between the request time and one calendar year later. Replace the example with a future instant in that range. pattern: "(Z|[+-]\d\d:\d\d)$"; format: "date-time" |
| timezone | string | optional; IANA timezone, default UTC. DST gaps are skipped and repeated local times fire once. default: "UTC" |
| start_at | string / null | optional; Optional RFC 3339 start time with timezone; null means no lower bound. |
| end_at | string / null | optional; Optional RFC 3339 end time with timezone; cannot precede start_at. null means no upper bound. |
| overlap | "skip" / "allow" | optional; skip (default) skips when a previous run is still active; allow permits overlapping runs. default: "skip" |
| catchup_window_seconds | integer | optional; Nonnegative integer seconds, default 300. Only scheduled firings delayed beyond the window are recorded as missed; webhooks ignore this window. default: 300; minimum: 0 |
| webhook | object | optional; input_mode is body (default) or envelope. The latter contains body, raw_body, raw_body_encoding, allowlisted headers, webhook_id and received_at; full URLs are returned only on creation or rotation. no additional fields. |
| webhook.input_mode | "body" / "envelope" | required; Shape of the input a webhook delivery gives the target. body (default) passes only the request body; envelope passes an object with body, raw_body, raw_body_encoding, headers, webhook_id and received_at. default: "body" |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TARGET | Published docs-samples/name@1.0.0 |
: "${TARGET:?Set TARGET}"
BODY=$(jq -n --arg TARGET "$TARGET" '{
"name": "sample-webhook",
"target": $TARGET,
"kind": "webhook",
"labels": {
"namespace": "docs-samples"
},
"webhook": {
"input_mode": "body"
}
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data "$BODY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.create({
"body": {
"name": "sample-webhook",
"target": env("TARGET"),
"kind": "webhook",
"labels": {
"namespace": "docs-samples"
},
"webhook": {
"input_mode": "body"
}
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| ETag | string | Current resource revision for conditional updates. |
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| Field | Type | Description |
|---|---|---|
| name | string | required; Trigger name, 1–100 characters. minLength: 1; maxLength: 100 |
| description | string | required; Trigger description, at most 1000 characters. maxLength: 1000 |
| labels | object | required; Trigger tags as string key and value pairs, at most 64; keys must not start with the reserved prefix praxis. (400 INPUT_INVALID). |
| target | string | required; Script or workflow to run, as ns/name@tag-or-version; it follows latest by default, and @1.2.0 pins a version. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| kind | "schedule" / "webhook" | required; Trigger kind. schedule fires on a plan (cron, every or at); webhook fires on an inbound HTTP request. |
| schedule | object / object / object / null | required; Schedule rule for kind=schedule, exactly one of cron, every or at; null for webhooks. |
| schedule (variant 1) (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule (variant 1) (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| schedule (variant 1) (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 3).at | string | required; Instant of a one-time firing (RFC 3339 UTC); it cannot be in the past or more than one year ahead. The trigger becomes expired after it runs. format: "date-time" |
| timezone | string | required; IANA time zone name used to interpret the schedule; UTC by default through the API. default: "UTC" |
| start_at | string / null | required; Start time of a scheduled trigger (RFC 3339 UTC); it does not fire before then. null for no limit. |
| end_at | string / null | required; End time of a scheduled trigger (RFC 3339 UTC); after it the trigger becomes expired. null for no end. |
| overlap | "skip" / "allow" | required; Overlap policy when a firing is due while the previous run is still active: skip (default) skips it, allow starts it anyway. default: "skip" |
| catchup_window_seconds | integer | required; Catch-up window in seconds, default 300, for scheduled triggers only: if a firing is later than this (downtime, pause) it is recorded as missed and not run. default: 300; minimum: 0 |
| webhook | object / null | required; Webhook settings for kind=webhook; null for scheduled triggers. |
| webhook (variant 1).input_mode | "body" / "envelope" | required; Shape of the input a webhook delivery gives the target. body (default) passes only the request body; envelope passes an object with body, raw_body, raw_body_encoding, headers, webhook_id and received_at. |
| webhook (variant 1).url_hint | string | required; Masked webhook address with an ellipsis replacing the secret token; it cannot be invoked. Newly created triggers use a full public URL; historical records may contain a relative /automation/v1/hooks/{id}/… path. |
| id | string | required; Trigger id, prefixed trg_; used in the webhook address and by every trigger endpoint. |
| owner | string | required; Tenant that owns the trigger, injected by the gateway; treat it as an opaque string. |
| state | "enabled" / "paused" / "expired" | required; Trigger state. enabled fires on schedule or request; paused does not fire; expired is final, reached after a one-time trigger has run or end_at has passed, and no longer fires. |
| source | "api" / "definition" | required; Origin of the trigger. api was created through the API and can be changed and deleted; definition was generated from the schedule in a workflow YAML and can only be paused or resumed, changes return 409 TRIGGER_MANAGED. |
| created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| created_by_user_id | string | required; Real user id of the creator, forwarded by the gateway; runs the trigger starts take their token from this user, for audit and usage attribution. |
| next_fire_times | string[] | required; Up to the next 5 firing times (RFC 3339 UTC); empty for webhook, paused or expired triggers. maxItems: 5 |
| last_firing | object / null | required; The most recent firing record, or null if it has never fired. |
| last_firing (variant 1).id | string | required; Firing record id; records are kept for 30 days. |
| last_firing (variant 1).trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| last_firing (variant 1).scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| last_firing (variant 1).fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| last_firing (variant 1).outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| last_firing (variant 1).run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| last_firing (variant 1).resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| last_firing (variant 1).error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| last_firing (variant 1).error (variant 1).code | string | required; Error code of the failure. |
| last_firing (variant 1).error (variant 1).message | string | required; Message describing the failure. |
| counts | object | required; Cumulative firing counts {started, skipped, missed, failed}. no additional fields. |
| counts.started | integer | required; Number of firings that started a run. minimum: 0 |
| counts.skipped | integer | required; Number of firings skipped because overlap is skip and the previous run was still active. minimum: 0 |
| counts.missed | integer | required; Number of firings missed because they were later than the catch-up window. minimum: 0 |
| counts.failed | integer | required; Number of firings where creating the run failed. minimum: 0 |
| created_at | string | required; Creation time (RFC 3339 UTC). format: "date-time" |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). format: "date-time" |
| etag | string | required; Current revision tag of the trigger; send it as If-Match when updating, and a mismatch returns 412. |
| usage_30d | object / null | optional; Always null in a create response; the 30-day usage is only returned by GET /triggers/{id}. |
| usage_30d (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage_30d (variant 1).cost | string | required; Rated actual charges as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage_30d (variant 1).pending_events | integer | required; Number of unrated usage events whose charges will be included later. minimum: 0 |
| webhook_url | string | optional; Returned only on webhook creation or rotation. format: "uri" |
HTTP 200
{
"id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"owner": "tnt_3a9759864ccb4e00",
"name": "sample-webhook-1791867412840-b05e8a",
"description": "",
"labels": {
"namespace": "docs-samples"
},
"target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
"input": {},
"kind": "webhook",
"schedule": null,
"timezone": "UTC",
"start_at": null,
"end_at": null,
"overlap": "skip",
"catchup_window_seconds": 300,
"webhook": {
"input_mode": "body",
"url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
},
"state": "enabled",
"source": "api",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"created_by_user_id": "usr_49d4fcb99517",
"next_fire_times": [],
"last_firing": null,
"counts": {
"started": 0,
"skipped": 0,
"missed": 0,
"failed": 0
},
"created_at": "2026-10-13T04:58:09.974Z",
"updated_at": "2026-10-13T04:58:09.974Z",
"etag": "etag_00mv67mzzqc6ef5487c69f4857b65b91dab497104c",
"webhook_url": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/${WEBHOOK_TOKEN}"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. SCHEDULE_INVALID: The schedule or time boundaries are invalid. TIMEZONE_INVALID: The timezone is not a valid IANA timezone. INTERVAL_TOO_SHORT: The schedule interval is shorter than one minute. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| 404 | TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. NO_MATCHING_VERSION: No published version matches the requested tag, version, or range. |
| 429 | TRIGGER_LIMIT: The tenant has reached the limit of 100 enabled triggers. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read schedule, state, upcoming times and latest firing. Use the ETag to update; the full webhook URL is not returned again.
GET /automation/v1/triggers/{id}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Trigger ID (trg_). |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.retrieve({
"path": {
"id": env("TRIGGER_ID")
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| ETag | string | Current resource revision for conditional updates. |
application/json
| Field | Type | Description |
|---|---|---|
| name | string | required; Trigger name, 1–100 characters. minLength: 1; maxLength: 100 |
| description | string | required; Trigger description, at most 1000 characters. maxLength: 1000 |
| labels | object | required; Trigger tags as string key and value pairs, at most 64; keys must not start with the reserved prefix praxis. (400 INPUT_INVALID). |
| target | string | required; Script or workflow to run, as ns/name@tag-or-version; it follows latest by default, and @1.2.0 pins a version. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| kind | "schedule" / "webhook" | required; Trigger kind. schedule fires on a plan (cron, every or at); webhook fires on an inbound HTTP request. |
| schedule | object / object / object / null | required; Schedule rule for kind=schedule, exactly one of cron, every or at; null for webhooks. |
| schedule (variant 1) (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule (variant 1) (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| schedule (variant 1) (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 3).at | string | required; Instant of a one-time firing (RFC 3339 UTC); it cannot be in the past or more than one year ahead. The trigger becomes expired after it runs. format: "date-time" |
| timezone | string | required; IANA time zone name used to interpret the schedule; UTC by default through the API. default: "UTC" |
| start_at | string / null | required; Start time of a scheduled trigger (RFC 3339 UTC); it does not fire before then. null for no limit. |
| end_at | string / null | required; End time of a scheduled trigger (RFC 3339 UTC); after it the trigger becomes expired. null for no end. |
| overlap | "skip" / "allow" | required; Overlap policy when a firing is due while the previous run is still active: skip (default) skips it, allow starts it anyway. default: "skip" |
| catchup_window_seconds | integer | required; Catch-up window in seconds, default 300, for scheduled triggers only: if a firing is later than this (downtime, pause) it is recorded as missed and not run. default: 300; minimum: 0 |
| webhook | object / null | required; Webhook settings for kind=webhook; null for scheduled triggers. |
| webhook (variant 1).input_mode | "body" / "envelope" | required; Shape of the input a webhook delivery gives the target. body (default) passes only the request body; envelope passes an object with body, raw_body, raw_body_encoding, headers, webhook_id and received_at. |
| webhook (variant 1).url_hint | string | required; Masked webhook address with an ellipsis replacing the secret token; it cannot be invoked. Newly created triggers use a full public URL; historical records may contain a relative /automation/v1/hooks/{id}/… path. |
| id | string | required; Trigger id, prefixed trg_; used in the webhook address and by every trigger endpoint. |
| owner | string | required; Tenant that owns the trigger, injected by the gateway; treat it as an opaque string. |
| state | "enabled" / "paused" / "expired" | required; Trigger state. enabled fires on schedule or request; paused does not fire; expired is final, reached after a one-time trigger has run or end_at has passed, and no longer fires. |
| source | "api" / "definition" | required; Origin of the trigger. api was created through the API and can be changed and deleted; definition was generated from the schedule in a workflow YAML and can only be paused or resumed, changes return 409 TRIGGER_MANAGED. |
| created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| created_by_user_id | string | required; Real user id of the creator, forwarded by the gateway; runs the trigger starts take their token from this user, for audit and usage attribution. |
| next_fire_times | string[] | required; Up to the next 5 firing times (RFC 3339 UTC); empty for webhook, paused or expired triggers. maxItems: 5 |
| last_firing | object / null | required; The most recent firing record, or null if it has never fired. |
| last_firing (variant 1).id | string | required; Firing record id; records are kept for 30 days. |
| last_firing (variant 1).trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| last_firing (variant 1).scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| last_firing (variant 1).fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| last_firing (variant 1).outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| last_firing (variant 1).run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| last_firing (variant 1).resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| last_firing (variant 1).error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| last_firing (variant 1).error (variant 1).code | string | required; Error code of the failure. |
| last_firing (variant 1).error (variant 1).message | string | required; Message describing the failure. |
| counts | object | required; Cumulative firing counts {started, skipped, missed, failed}. no additional fields. |
| counts.started | integer | required; Number of firings that started a run. minimum: 0 |
| counts.skipped | integer | required; Number of firings skipped because overlap is skip and the previous run was still active. minimum: 0 |
| counts.missed | integer | required; Number of firings missed because they were later than the catch-up window. minimum: 0 |
| counts.failed | integer | required; Number of firings where creating the run failed. minimum: 0 |
| created_at | string | required; Creation time (RFC 3339 UTC). format: "date-time" |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). format: "date-time" |
| etag | string | required; Current revision tag of the trigger; send it as If-Match when updating, and a mismatch returns 412. |
| usage_30d | object / null | optional; Returned only by GET /triggers/{id}, omitted from lists. Attributed charges over the preceding 30 days for this trigger's runs and descendants. Runs themselves are free; these are actual charges for capabilities such as models and search called during runs, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage_30d (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage_30d (variant 1).cost | string | required; Rated actual charges as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage_30d (variant 1).pending_events | integer | required; Number of unrated usage events whose charges will be included later. minimum: 0 |
HTTP 200
{
"id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"owner": "tnt_3a9759864ccb4e00",
"name": "sample-webhook-1791867412840-b05e8a",
"description": "",
"labels": {
"namespace": "docs-samples"
},
"target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
"input": {},
"kind": "webhook",
"schedule": null,
"timezone": "UTC",
"start_at": null,
"end_at": null,
"overlap": "skip",
"catchup_window_seconds": 300,
"webhook": {
"input_mode": "body",
"url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
},
"state": "paused",
"source": "api",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"created_by_user_id": "usr_49d4fcb99517",
"next_fire_times": [],
"last_firing": null,
"counts": {
"started": 0,
"skipped": 0,
"missed": 0,
"failed": 0
},
"created_at": "2026-10-13T04:58:09.974Z",
"updated_at": "2026-10-13T04:58:12.519Z",
"etag": "etag_00mv67n1yf40e7b8d39ce5459d9ce835bfb1083701",
"usage_30d": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Update configuration with If-Match matching the current ETag, revalidating target input and schedule. kind is immutable and definition-managed triggers reject updates with TRIGGER_MANAGED.
PATCH /automation/v1/triggers/{id}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Trigger ID (trg_). |
| header: If-Match | string | required; Current resource ETag. The value of the object's draft.revision or etag field can be used directly: the bare value, the quoted form and the weak form W/"…" are all accepted (RFC 7232 weak comparison). Omission returns 400 and a revision mismatch returns 412. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| name | string | optional; Trigger display name, 1–100 characters and not all whitespace; uniqueness is not required. minLength: 1; maxLength: 100 |
| description | string | optional; Description, at most 1,000 characters. maxLength: 1000 |
| labels | object | optional; At most 64 user labels; the praxis. prefix is reserved and internal labels do not count. Keys 1–40 characters, values at most 500. |
| target | string | optional; ns/name@tag or ns/name@version, defaulting to latest when @ is omitted. Triggers do not accept version ranges. |
| input | null / string / number / boolean / object / null / string / number / boolean / object / JSON[][] | optional; Static JSON input for scheduled firings, default {}; checked against the target schema on create/update. Omitted webhook input is not validated at creation. |
| input (variant 5).* (variant 5) | object | Recursive JSON value. |
| input (variant 5).* (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| kind | "schedule" / "webhook" | optional; schedule fires on a schedule; webhook fires on an HTTP delivery. Immutable after creation. |
| schedule | object / object / object | optional; Choose one: a five-field cron (L/W/# supported), every as an ISO 8601 duration or duration object resolving to positive integer milliseconds from one minute to 366 days, or at as a one-time RFC 3339 timestamp within the next year. |
| schedule (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| schedule (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| schedule (variant 3).at | string | required; One-time firing instant with a Z or ±HH:MM timezone, between the request time and one calendar year later. Replace the example with a future instant in that range. pattern: "(Z|[+-]\d\d:\d\d)$"; format: "date-time" |
| timezone | string | optional; IANA timezone, default UTC. DST gaps are skipped and repeated local times fire once. default: "UTC" |
| start_at | string / null | optional; Optional RFC 3339 start time with timezone; null means no lower bound. |
| end_at | string / null | optional; Optional RFC 3339 end time with timezone; cannot precede start_at. null means no upper bound. |
| overlap | "skip" / "allow" | optional; skip (default) skips when a previous run is still active; allow permits overlapping runs. default: "skip" |
| catchup_window_seconds | integer | optional; Nonnegative integer seconds, default 300. Only scheduled firings delayed beyond the window are recorded as missed; webhooks ignore this window. default: 300; minimum: 0 |
| webhook | object | optional; input_mode is body (default) or envelope. The latter contains body, raw_body, raw_body_encoding, allowlisted headers, webhook_id and received_at; full URLs are returned only on creation or rotation. no additional fields. |
| webhook.input_mode | "body" / "envelope" | required; Shape of the input a webhook delivery gives the target. body (default) passes only the request body; envelope passes an object with body, raw_body, raw_body_encoding, headers, webhook_id and received_at. default: "body" |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
| ETAG | Latest GET response ETag header (preserve quotes) |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
: "${ETAG:?Set ETAG}"
curl --fail-with-body -X PATCH "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "If-Match: ${ETAG}" \
-H "Content-Type: application/json" \
--data '{
"description": "Sample webhook",
"input": {
"n": 41
}
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.update({
"path": {
"id": env("TRIGGER_ID")
},
"headers": {
"If-Match": env("ETAG")
},
"body": {
"description": "Sample webhook",
"input": {
"n": 41
}
}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| ETag | string | Current resource revision for conditional updates. |
application/json
| Field | Type | Description |
|---|---|---|
| name | string | required; Trigger name, 1–100 characters. minLength: 1; maxLength: 100 |
| description | string | required; Trigger description, at most 1000 characters. maxLength: 1000 |
| labels | object | required; Trigger tags as string key and value pairs, at most 64; keys must not start with the reserved prefix praxis. (400 INPUT_INVALID). |
| target | string | required; Script or workflow to run, as ns/name@tag-or-version; it follows latest by default, and @1.2.0 pins a version. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| kind | "schedule" / "webhook" | required; Trigger kind. schedule fires on a plan (cron, every or at); webhook fires on an inbound HTTP request. |
| schedule | object / object / object / null | required; Schedule rule for kind=schedule, exactly one of cron, every or at; null for webhooks. |
| schedule (variant 1) (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule (variant 1) (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| schedule (variant 1) (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 3).at | string | required; Instant of a one-time firing (RFC 3339 UTC); it cannot be in the past or more than one year ahead. The trigger becomes expired after it runs. format: "date-time" |
| timezone | string | required; IANA time zone name used to interpret the schedule; UTC by default through the API. default: "UTC" |
| start_at | string / null | required; Start time of a scheduled trigger (RFC 3339 UTC); it does not fire before then. null for no limit. |
| end_at | string / null | required; End time of a scheduled trigger (RFC 3339 UTC); after it the trigger becomes expired. null for no end. |
| overlap | "skip" / "allow" | required; Overlap policy when a firing is due while the previous run is still active: skip (default) skips it, allow starts it anyway. default: "skip" |
| catchup_window_seconds | integer | required; Catch-up window in seconds, default 300, for scheduled triggers only: if a firing is later than this (downtime, pause) it is recorded as missed and not run. default: 300; minimum: 0 |
| webhook | object / null | required; Webhook settings for kind=webhook; null for scheduled triggers. |
| webhook (variant 1).input_mode | "body" / "envelope" | required; Shape of the input a webhook delivery gives the target. body (default) passes only the request body; envelope passes an object with body, raw_body, raw_body_encoding, headers, webhook_id and received_at. |
| webhook (variant 1).url_hint | string | required; Masked webhook address with an ellipsis replacing the secret token; it cannot be invoked. Newly created triggers use a full public URL; historical records may contain a relative /automation/v1/hooks/{id}/… path. |
| id | string | required; Trigger id, prefixed trg_; used in the webhook address and by every trigger endpoint. |
| owner | string | required; Tenant that owns the trigger, injected by the gateway; treat it as an opaque string. |
| state | "enabled" / "paused" / "expired" | required; Trigger state. enabled fires on schedule or request; paused does not fire; expired is final, reached after a one-time trigger has run or end_at has passed, and no longer fires. |
| source | "api" / "definition" | required; Origin of the trigger. api was created through the API and can be changed and deleted; definition was generated from the schedule in a workflow YAML and can only be paused or resumed, changes return 409 TRIGGER_MANAGED. |
| created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| created_by_user_id | string | required; Real user id of the creator, forwarded by the gateway; runs the trigger starts take their token from this user, for audit and usage attribution. |
| next_fire_times | string[] | required; Up to the next 5 firing times (RFC 3339 UTC); empty for webhook, paused or expired triggers. maxItems: 5 |
| last_firing | object / null | required; The most recent firing record, or null if it has never fired. |
| last_firing (variant 1).id | string | required; Firing record id; records are kept for 30 days. |
| last_firing (variant 1).trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| last_firing (variant 1).scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| last_firing (variant 1).fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| last_firing (variant 1).outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| last_firing (variant 1).run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| last_firing (variant 1).resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| last_firing (variant 1).error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| last_firing (variant 1).error (variant 1).code | string | required; Error code of the failure. |
| last_firing (variant 1).error (variant 1).message | string | required; Message describing the failure. |
| counts | object | required; Cumulative firing counts {started, skipped, missed, failed}. no additional fields. |
| counts.started | integer | required; Number of firings that started a run. minimum: 0 |
| counts.skipped | integer | required; Number of firings skipped because overlap is skip and the previous run was still active. minimum: 0 |
| counts.missed | integer | required; Number of firings missed because they were later than the catch-up window. minimum: 0 |
| counts.failed | integer | required; Number of firings where creating the run failed. minimum: 0 |
| created_at | string | required; Creation time (RFC 3339 UTC). format: "date-time" |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). format: "date-time" |
| etag | string | required; Current revision tag of the trigger; send it as If-Match when updating, and a mismatch returns 412. |
| usage_30d | object / null | optional; Returned only by GET /triggers/{id}, omitted from lists. Attributed charges over the preceding 30 days for this trigger's runs and descendants. Runs themselves are free; these are actual charges for capabilities such as models and search called during runs, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage_30d (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage_30d (variant 1).cost | string | required; Rated actual charges as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage_30d (variant 1).pending_events | integer | required; Number of unrated usage events whose charges will be included later. minimum: 0 |
HTTP 200
{
"id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"owner": "tnt_3a9759864ccb4e00",
"name": "sample-webhook-1791867412840-b05e8a",
"description": "Sample webhook",
"labels": {
"namespace": "docs-samples"
},
"target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
"input": {
"n": 41
},
"kind": "webhook",
"schedule": null,
"timezone": "UTC",
"start_at": null,
"end_at": null,
"overlap": "skip",
"catchup_window_seconds": 300,
"webhook": {
"input_mode": "body",
"url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
},
"state": "paused",
"source": "api",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"created_by_user_id": "usr_49d4fcb99517",
"next_fire_times": [],
"last_firing": null,
"counts": {
"started": 0,
"skipped": 0,
"missed": 0,
"failed": 0
},
"created_at": "2026-10-13T04:58:09.974Z",
"updated_at": "2026-10-13T04:58:14.661Z",
"etag": "etag_00mv67n3ib18c0371214b84064b86e9375320685fa"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. SCHEDULE_INVALID: The schedule or time boundaries are invalid. TIMEZONE_INVALID: The timezone is not a valid IANA timezone. INTERVAL_TOO_SHORT: The schedule interval is shorter than one minute. INPUT_INVALID: The input does not satisfy the target contract or validation rules. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. TARGET_NOT_FOUND: The target does not exist or has an incompatible type. VERSION_NOT_FOUND: The requested version or revision does not exist. |
| 409 | TRIGGER_MANAGED: The trigger is managed by a definition and cannot be modified directly. TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 422 | NO_MATCHING_VERSION: No published version matches the requested tag, version, or range. |
| 429 | TRIGGER_LIMIT: The tenant has reached the limit of 100 enabled triggers. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Delete the trigger and its firing history, returning 204. Runs already started are unaffected. Definition-managed triggers return 409 TRIGGER_MANAGED; remove schedule from the workflow and publish it again.
DELETE /automation/v1/triggers/{id}
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Trigger ID (trg_). |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X DELETE "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.delete({
"path": {
"id": env("TRIGGER_ID")
}
});
console.log(result);Deleted
HTTP 204
| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| 409 | TRIGGER_MANAGED: The trigger is managed by a definition and cannot be modified directly. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Pause new firings without terminating existing runs. Definition-managed triggers can also be paused.
POST /automation/v1/triggers/{id}/pause
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Trigger ID (trg_). |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/pause" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.pause({
"path": {
"id": env("TRIGGER_ID")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| name | string | required; Trigger name, 1–100 characters. minLength: 1; maxLength: 100 |
| description | string | required; Trigger description, at most 1000 characters. maxLength: 1000 |
| labels | object | required; Trigger tags as string key and value pairs, at most 64; keys must not start with the reserved prefix praxis. (400 INPUT_INVALID). |
| target | string | required; Script or workflow to run, as ns/name@tag-or-version; it follows latest by default, and @1.2.0 pins a version. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| kind | "schedule" / "webhook" | required; Trigger kind. schedule fires on a plan (cron, every or at); webhook fires on an inbound HTTP request. |
| schedule | object / object / object / null | required; Schedule rule for kind=schedule, exactly one of cron, every or at; null for webhooks. |
| schedule (variant 1) (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule (variant 1) (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| schedule (variant 1) (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 3).at | string | required; Instant of a one-time firing (RFC 3339 UTC); it cannot be in the past or more than one year ahead. The trigger becomes expired after it runs. format: "date-time" |
| timezone | string | required; IANA time zone name used to interpret the schedule; UTC by default through the API. default: "UTC" |
| start_at | string / null | required; Start time of a scheduled trigger (RFC 3339 UTC); it does not fire before then. null for no limit. |
| end_at | string / null | required; End time of a scheduled trigger (RFC 3339 UTC); after it the trigger becomes expired. null for no end. |
| overlap | "skip" / "allow" | required; Overlap policy when a firing is due while the previous run is still active: skip (default) skips it, allow starts it anyway. default: "skip" |
| catchup_window_seconds | integer | required; Catch-up window in seconds, default 300, for scheduled triggers only: if a firing is later than this (downtime, pause) it is recorded as missed and not run. default: 300; minimum: 0 |
| webhook | object / null | required; Webhook settings for kind=webhook; null for scheduled triggers. |
| webhook (variant 1).input_mode | "body" / "envelope" | required; Shape of the input a webhook delivery gives the target. body (default) passes only the request body; envelope passes an object with body, raw_body, raw_body_encoding, headers, webhook_id and received_at. |
| webhook (variant 1).url_hint | string | required; Masked webhook address with an ellipsis replacing the secret token; it cannot be invoked. Newly created triggers use a full public URL; historical records may contain a relative /automation/v1/hooks/{id}/… path. |
| id | string | required; Trigger id, prefixed trg_; used in the webhook address and by every trigger endpoint. |
| owner | string | required; Tenant that owns the trigger, injected by the gateway; treat it as an opaque string. |
| state | "enabled" / "paused" / "expired" | required; Trigger state. enabled fires on schedule or request; paused does not fire; expired is final, reached after a one-time trigger has run or end_at has passed, and no longer fires. |
| source | "api" / "definition" | required; Origin of the trigger. api was created through the API and can be changed and deleted; definition was generated from the schedule in a workflow YAML and can only be paused or resumed, changes return 409 TRIGGER_MANAGED. |
| created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| created_by_user_id | string | required; Real user id of the creator, forwarded by the gateway; runs the trigger starts take their token from this user, for audit and usage attribution. |
| next_fire_times | string[] | required; Up to the next 5 firing times (RFC 3339 UTC); empty for webhook, paused or expired triggers. maxItems: 5 |
| last_firing | object / null | required; The most recent firing record, or null if it has never fired. |
| last_firing (variant 1).id | string | required; Firing record id; records are kept for 30 days. |
| last_firing (variant 1).trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| last_firing (variant 1).scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| last_firing (variant 1).fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| last_firing (variant 1).outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| last_firing (variant 1).run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| last_firing (variant 1).resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| last_firing (variant 1).error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| last_firing (variant 1).error (variant 1).code | string | required; Error code of the failure. |
| last_firing (variant 1).error (variant 1).message | string | required; Message describing the failure. |
| counts | object | required; Cumulative firing counts {started, skipped, missed, failed}. no additional fields. |
| counts.started | integer | required; Number of firings that started a run. minimum: 0 |
| counts.skipped | integer | required; Number of firings skipped because overlap is skip and the previous run was still active. minimum: 0 |
| counts.missed | integer | required; Number of firings missed because they were later than the catch-up window. minimum: 0 |
| counts.failed | integer | required; Number of firings where creating the run failed. minimum: 0 |
| created_at | string | required; Creation time (RFC 3339 UTC). format: "date-time" |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). format: "date-time" |
| etag | string | required; Current revision tag of the trigger; send it as If-Match when updating, and a mismatch returns 412. |
| usage_30d | object / null | optional; Returned only by GET /triggers/{id}, omitted from lists. Attributed charges over the preceding 30 days for this trigger's runs and descendants. Runs themselves are free; these are actual charges for capabilities such as models and search called during runs, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage_30d (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage_30d (variant 1).cost | string | required; Rated actual charges as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage_30d (variant 1).pending_events | integer | required; Number of unrated usage events whose charges will be included later. minimum: 0 |
HTTP 200
{
"id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"owner": "tnt_3a9759864ccb4e00",
"name": "sample-webhook-1791867412840-b05e8a",
"description": "",
"labels": {
"namespace": "docs-samples"
},
"target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
"input": {},
"kind": "webhook",
"schedule": null,
"timezone": "UTC",
"start_at": null,
"end_at": null,
"overlap": "skip",
"catchup_window_seconds": 300,
"webhook": {
"input_mode": "body",
"url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
},
"state": "paused",
"source": "api",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"created_by_user_id": "usr_49d4fcb99517",
"next_fire_times": [],
"last_firing": null,
"counts": {
"started": 0,
"skipped": 0,
"missed": 0,
"failed": 0
},
"created_at": "2026-10-13T04:58:09.974Z",
"updated_at": "2026-10-13T04:58:12.519Z",
"etag": "etag_00mv67n1yf40e7b8d39ce5459d9ce835bfb1083701"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Resume firings and reset consecutive failures. Triggers past their end time or finished one-time schedules remain expired; a full enabled-trigger quota returns TRIGGER_LIMIT.
POST /automation/v1/triggers/{id}/resume
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Trigger ID (trg_). |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/resume" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.resume({
"path": {
"id": env("TRIGGER_ID")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| name | string | required; Trigger name, 1–100 characters. minLength: 1; maxLength: 100 |
| description | string | required; Trigger description, at most 1000 characters. maxLength: 1000 |
| labels | object | required; Trigger tags as string key and value pairs, at most 64; keys must not start with the reserved prefix praxis. (400 INPUT_INVALID). |
| target | string | required; Script or workflow to run, as ns/name@tag-or-version; it follows latest by default, and @1.2.0 pins a version. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| kind | "schedule" / "webhook" | required; Trigger kind. schedule fires on a plan (cron, every or at); webhook fires on an inbound HTTP request. |
| schedule | object / object / object / null | required; Schedule rule for kind=schedule, exactly one of cron, every or at; null for webhooks. |
| schedule (variant 1) (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule (variant 1) (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| schedule (variant 1) (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| schedule (variant 1) (variant 3).at | string | required; Instant of a one-time firing (RFC 3339 UTC); it cannot be in the past or more than one year ahead. The trigger becomes expired after it runs. format: "date-time" |
| timezone | string | required; IANA time zone name used to interpret the schedule; UTC by default through the API. default: "UTC" |
| start_at | string / null | required; Start time of a scheduled trigger (RFC 3339 UTC); it does not fire before then. null for no limit. |
| end_at | string / null | required; End time of a scheduled trigger (RFC 3339 UTC); after it the trigger becomes expired. null for no end. |
| overlap | "skip" / "allow" | required; Overlap policy when a firing is due while the previous run is still active: skip (default) skips it, allow starts it anyway. default: "skip" |
| catchup_window_seconds | integer | required; Catch-up window in seconds, default 300, for scheduled triggers only: if a firing is later than this (downtime, pause) it is recorded as missed and not run. default: 300; minimum: 0 |
| webhook | object / null | required; Webhook settings for kind=webhook; null for scheduled triggers. |
| webhook (variant 1).input_mode | "body" / "envelope" | required; Shape of the input a webhook delivery gives the target. body (default) passes only the request body; envelope passes an object with body, raw_body, raw_body_encoding, headers, webhook_id and received_at. |
| webhook (variant 1).url_hint | string | required; Masked webhook address with an ellipsis replacing the secret token; it cannot be invoked. Newly created triggers use a full public URL; historical records may contain a relative /automation/v1/hooks/{id}/… path. |
| id | string | required; Trigger id, prefixed trg_; used in the webhook address and by every trigger endpoint. |
| owner | string | required; Tenant that owns the trigger, injected by the gateway; treat it as an opaque string. |
| state | "enabled" / "paused" / "expired" | required; Trigger state. enabled fires on schedule or request; paused does not fire; expired is final, reached after a one-time trigger has run or end_at has passed, and no longer fires. |
| source | "api" / "definition" | required; Origin of the trigger. api was created through the API and can be changed and deleted; definition was generated from the schedule in a workflow YAML and can only be paused or resumed, changes return 409 TRIGGER_MANAGED. |
| created_by | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| created_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| created_by.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| created_by_user_id | string | required; Real user id of the creator, forwarded by the gateway; runs the trigger starts take their token from this user, for audit and usage attribution. |
| next_fire_times | string[] | required; Up to the next 5 firing times (RFC 3339 UTC); empty for webhook, paused or expired triggers. maxItems: 5 |
| last_firing | object / null | required; The most recent firing record, or null if it has never fired. |
| last_firing (variant 1).id | string | required; Firing record id; records are kept for 30 days. |
| last_firing (variant 1).trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| last_firing (variant 1).scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| last_firing (variant 1).fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| last_firing (variant 1).outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| last_firing (variant 1).run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| last_firing (variant 1).resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| last_firing (variant 1).error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| last_firing (variant 1).error (variant 1).code | string | required; Error code of the failure. |
| last_firing (variant 1).error (variant 1).message | string | required; Message describing the failure. |
| counts | object | required; Cumulative firing counts {started, skipped, missed, failed}. no additional fields. |
| counts.started | integer | required; Number of firings that started a run. minimum: 0 |
| counts.skipped | integer | required; Number of firings skipped because overlap is skip and the previous run was still active. minimum: 0 |
| counts.missed | integer | required; Number of firings missed because they were later than the catch-up window. minimum: 0 |
| counts.failed | integer | required; Number of firings where creating the run failed. minimum: 0 |
| created_at | string | required; Creation time (RFC 3339 UTC). format: "date-time" |
| updated_at | string | required; Time of the last update (RFC 3339 UTC). format: "date-time" |
| etag | string | required; Current revision tag of the trigger; send it as If-Match when updating, and a mismatch returns 412. |
| usage_30d | object / null | optional; Returned only by GET /triggers/{id}, omitted from lists. Attributed charges over the preceding 30 days for this trigger's runs and descendants. Runs themselves are free; these are actual charges for capabilities such as models and search called during runs, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage_30d (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage_30d (variant 1).cost | string | required; Rated actual charges as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage_30d (variant 1).pending_events | integer | required; Number of unrated usage events whose charges will be included later. minimum: 0 |
HTTP 200
{
"id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"owner": "tnt_3a9759864ccb4e00",
"name": "sample-webhook-1791867412840-b05e8a",
"description": "Sample webhook",
"labels": {
"namespace": "docs-samples"
},
"target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
"input": {
"n": 41
},
"kind": "webhook",
"schedule": null,
"timezone": "UTC",
"start_at": null,
"end_at": null,
"overlap": "skip",
"catchup_window_seconds": 300,
"webhook": {
"input_mode": "body",
"url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
},
"state": "enabled",
"source": "api",
"created_by": {
"type": "api_key",
"id": "key_3e00b8984967"
},
"created_by_user_id": "usr_49d4fcb99517",
"next_fire_times": [],
"last_firing": null,
"counts": {
"started": 0,
"skipped": 0,
"missed": 0,
"failed": 0
},
"created_at": "2026-10-13T04:58:09.974Z",
"updated_at": "2026-10-13T04:58:17.058Z",
"etag": "etag_00mv67n5gidea13751125d4ad292fb95b07fac032e"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 429 | TRIGGER_LIMIT: The tenant has reached the limit of 100 enabled triggers. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Fire once now and return a Firing, subject to current state, catchup window and overlap rules. Run-launch failures are recorded in the firing error.
POST /automation/v1/triggers/{id}/fire
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Trigger ID (trg_). |
| header: Idempotency-Key | string | optional; Optional; 1–256 characters. Within 24 hours, the same key replays the first response with Idempotent-Replayed: true; a different request body returns 422; an in-flight request returns 409. minLength: 1; maxLength: 256 |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/fire" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.fire({
"path": {
"id": env("TRIGGER_ID")
},
"body": {}
});
console.log(result);Success
| Header | Type | Description |
|---|---|---|
| Idempotent-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Firing record id; records are kept for 30 days. |
| trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| error (variant 1).code | string | required; Error code of the failure. |
| error (variant 1).message | string | required; Message describing the failure. |
HTTP 200
{
"id": "frg_00mv67n833fec8a47a90904782ac1a8f1fef264379",
"trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"scheduled_at": "2026-10-13T04:58:20.215Z",
"fired_at": "2026-10-13T04:58:20.215Z",
"outcome": "started",
"run_id": "run_00mv67n8ao7de994212f453fdfe7def756b57ec5cdeb562a1222f554c6f3d9f428ec25480e",
"resolved_version": "1.0.0",
"error": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| 409 | IDEMPOTENCY_IN_FLIGHT: A request with the same idempotency key is still in progress. RUN_INVALID_STATE: The current state does not allow this action. |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 422 | IDEMPOTENCY_KEY_MISMATCH: The idempotency key was already used for different request content. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
For webhook triggers only: invalidate the old token immediately and return a new full webhook_url. Later detail reads do not reveal the full URL.
POST /automation/v1/triggers/{id}/rotate-webhook
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Trigger ID (trg_). |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/rotate-webhook" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.rotateWebhook({
"path": {
"id": env("TRIGGER_ID")
},
"body": {}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| webhook_url | string | required; The new full webhook URL including its secret token; returned only once, so store it safely, and rotate again if it is lost. The previous URL stops working immediately. format: "uri" |
HTTP 200
{
"webhook_url": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/${WEBHOOK_TOKEN}"
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Read the last 30 days of firings newest first. Results include resolved versions, run IDs and failure details.
GET /automation/v1/triggers/{id}/firings
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Trigger ID (trg_). |
| query: limit | integer | optional; Page size: integer 1–100, default 25. minimum: 1; maximum: 100 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"[] | optional; Filter outcomes using comma-separated values (OR); combined with run_id using AND. |
| query: run_id | string | optional; Return only firings associated with this exact run ID. |
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/firings" \
-H "Authorization: Bearer $PRAXIS_API_KEY"import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.firings.list({
"path": {
"id": env("TRIGGER_ID")
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object[] | required; Firing records from the last 30 days on this page, ordered by created_at descending, then id descending. |
| data[].id | string | required; Firing record id; records are kept for 30 days. |
| data[].trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| data[].scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| data[].fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| data[].outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| data[].run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| data[].resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| data[].error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| data[].error (variant 1).code | string | required; Error code of the failure. |
| data[].error (variant 1).message | string | required; Message describing the failure. |
| next_cursor | string / null | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
HTTP 200
{
"data": [
{
"id": "frg_00mv67n833fec8a47a90904782ac1a8f1fef264379",
"trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"scheduled_at": "2026-10-13T04:58:20.215Z",
"fired_at": "2026-10-13T04:58:20.215Z",
"outcome": "started",
"run_id": "run_00mv67n8ao7de994212f453fdfe7def756b57ec5cdeb562a1222f554c6f3d9f428ec25480e",
"resolved_version": "1.0.0",
"error": null
},
{
"id": "frg_00mv67n6in516077a64cfc4102a4da939476a3fa78",
"trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"scheduled_at": "2026-10-13T04:58:18.384Z",
"fired_at": "2026-10-13T04:58:18.384Z",
"outcome": "started",
"run_id": "run_00mv67n6vvebb47a96bf4b54630d8a07786ec923a68d3b722c2f7ffca4e0a553053c4a5421",
"resolved_version": "1.0.0",
"error": null
}
],
"next_cursor": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
Validate a schedule and preview up to five future firing times. The timezone is validated and a readable description is returned, without creating a trigger or run.
POST /automation/v1/triggers/preview
Authorization: Bearer $PRAXIS_API_KEY
| Parameter | Type | Description |
|---|---|---|
| header: Accept-Language | string | optional; Language for the readable description; supports Chinese (default) and English by language quality preference. |
no additional fields.
| Field | Type | Description |
|---|---|---|
| schedule | object / object / object | required; Choose a five-field cron (L/W/# supported), every of at least one minute, or at with a timezone. Uses the same validation as creation; at must be between now and one year ahead; every must resolve to positive integer milliseconds no longer than 366 days. |
| schedule (variant 1).cron | string | required; Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule (variant 2).every | string / object | required; A duration: an ISO 8601 string such as PT5M, or an object with days, hours, minutes, seconds and milliseconds. It must convert to a whole number of milliseconds between 60000 and 31622400000 (1 minute to 366 days). |
| schedule (variant 2).every (variant 2).days | integer | optional; Number of days, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).hours | integer | optional; Number of hours, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).minutes | integer | optional; Number of minutes, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).seconds | integer | optional; Number of seconds, a non-negative integer. minimum: 0 |
| schedule (variant 2).every (variant 2).milliseconds | integer | optional; Number of milliseconds, a non-negative integer. minimum: 0 |
| schedule (variant 3).at | string | required; One-time firing instant with a Z or ±HH:MM timezone, between the request time and one calendar year later. Replace the example with a future instant in that range. pattern: "(Z|[+-]\d\d:\d\d)$"; format: "date-time" |
| timezone | string | optional; IANA timezone, default UTC. DST gaps are skipped and repeated local times fire once. |
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/preview" \
-H "Authorization: Bearer $PRAXIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"schedule": {
"cron": "0 9 * * *"
},
"timezone": "UTC"
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: env('PRAXIS_API_KEY'),
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.triggers.preview({
"body": {
"schedule": {
"cron": "0 9 * * *"
},
"timezone": "UTC"
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| description | string | required; Human-readable description of the rule; common cron expressions are spelled out and others echo the expression. The language follows Accept-Language, Chinese by default. |
| next_fire_times | string[] | required; Up to the next 5 firing times for the rule and time zone (RFC 3339 UTC). maxItems: 5 |
HTTP 200
{
"description": "每天 09:00 · UTC",
"next_fire_times": [
"2026-10-13T09:00:00.000Z",
"2026-10-14T09:00:00.000Z",
"2026-10-15T09:00:00.000Z",
"2026-10-16T09:00:00.000Z",
"2026-10-17T09:00:00.000Z"
]
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. SCHEDULE_INVALID: The schedule or time boundaries are invalid. TIMEZONE_INVALID: The timezone is not a valid IANA timezone. INTERVAL_TOO_SHORT: The schedule interval is shorter than one minute. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.
No API key is needed: the URL token authenticates requests. Invalid tokens, absent triggers, wrong kinds and inactive time windows return 404; a paused trigger (circuit breaker after 5 consecutive failures, or manual pause) returns 409 TRIGGER_PAUSED whose message gives the reason and whose hint gives the way back, POST /automation/v1/triggers/{id}/resume. Raw bodies are limited to 512 KiB; serialized run input, including raw and parsed copies, must fit within 1 MiB. Exceeding either limit returns 413 synchronously without recording a firing; webhook-id deduplicates for 24 hours. A 202 with outcome=accepted acknowledges receipt; the final outcome is updated later, and repeats return deduped. Invalid JSON yields body=null; other UTF-8 is text and non-UTF-8 is base64. The envelope contains body, raw_body, raw_body_encoding, allowlisted headers, webhook_id and received_at. raw_body preserves exact bytes with utf8 or base64 encoding for caller-side signature verification.
POST /automation/v1/hooks/{trigger_id}/{token}
Use the webhook URL returned on creation or rotation. The path token is the credential; no Bearer Key is required.
| Parameter | Type | Description |
|---|---|---|
| path: trigger_id | string | required; Trigger ID (trg_). |
| path: token | string | required; Secret URL token returned on creation or rotation; do not disclose it. |
| header: webhook-id | string | optional; Optional deduplication identifier, retained for 24 hours within this trigger. |
Any JSON value: null, boolean, number, string, array or object.
| Field | Type | Description |
|---|---|---|
| (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
string
string
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
| WEBHOOK_TOKEN | Last segment of the new webhook_url; keep it private |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
: "${WEBHOOK_TOKEN:?Set WEBHOOK_TOKEN}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/hooks/${TRIGGER_ID}/${WEBHOOK_TOKEN}" \
-H "Content-Type: application/json" \
--data '{
"n": 41
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: '',
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.hooks.send({
"path": {
"trigger_id": env("TRIGGER_ID"),
"token": env("WEBHOOK_TOKEN")
},
"body": {
"n": 41
}
});
console.log(result);Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Firing record id; records are kept for 30 days. |
| trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| error (variant 1).code | string | required; Error code of the failure. |
| error (variant 1).message | string | required; Message describing the failure. |
HTTP 202
{
"id": "frg_00mv67n6in516077a64cfc4102a4da939476a3fa78",
"trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"scheduled_at": "2026-10-13T04:58:18.384Z",
"fired_at": "2026-10-13T04:58:18.384Z",
"outcome": "accepted",
"run_id": null,
"resolved_version": null,
"error": null
}| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| 405 | METHOD_NOT_ALLOWED: Only POST is supported; other methods return 405 before authentication with Allow: POST. |
| 409 | TRIGGER_PAUSED: The trigger is paused, either automatically by the circuit breaker after 5 consecutive firing failures or manually; the response message gives the reason and the hint gives the way back: resume the trigger (triggers.resume). |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 413 | PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.