Automation
Create an action
Create an action definition and its first revision, folding names to lowercase.
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
Authentication
Authorization: Bearer $PRAXIS_API_KEY
Request fields
| 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 |
application/json
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. |
Examples
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);Response
HTTP 200
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). |
Measured response
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"
}Errors
| 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.