Automation

Update an action

Update after checking compatibility against the current and five recent revisions.

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}

Authentication

Authorization: Bearer $PRAXIS_API_KEY

Request fields

ParameterTypeDescription
path: nsstringrequired; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only.
path: namestringrequired; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}.
query: dry_runbooleanoptional; true checks compatibility without persisting and may omit If-Match; omitted or false performs a normal update.
header: If-Matchstringoptional; Required for normal updates; optional for dry_run=true but still validated when supplied. * matches any existing representation; otherwise supply the current revision ETag.

application/json

no additional fields.

FieldTypeDescription
descriptionstringoptional; Description, at most 1,000 characters. maxLength: 1000
labelsobjectoptional; At most 50 labels; keys contain 1–40 characters and values at most 500 characters.
input_schemaobjectrequired; 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_schemaobjectrequired; 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.
errorsobject[]optional; Declared error types and descriptions; existing errors cannot be removed during updates.
errors[].typestringrequired; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime.
errors[].codestringoptional; Optional stable error code callers can branch on.
errors[].descriptionstringrequired; What this error means and when it occurs, written for callers.
annotationsobjectoptional; Boolean read_only and idempotent annotations, both defaulting to false. no additional fields.
annotations.read_onlybooleanoptional; true declares that the action does not change external state and only reads data. Defaults to false.
annotations.idempotentbooleanoptional; 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_msnumberoptional; Positive integer milliseconds; code defaults to and is capped at 30,000. container/shell are not yet available.
implementationobject / object / objectrequired; 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).sourcestringrequired; 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).imagestringrequired; Container image reference.
implementation (variant 2).commandstring[]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).scriptstringrequired; Full text of the shell script to run.
messagestringoptional; A message describing this revision.

Examples

Set these environment variables to your own resources:

: "${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);

Response

HTTP 200

Success

HeaderTypeDescription
ETagstringCurrent revision returned only for normal updates; absent for dry_run=true.

application/json

FieldTypeDescription
(variant 1).idstringrequired; Action id, prefixed act_; calls normally use namespace and name instead of the id.
(variant 1).namespacestringrequired; Action namespace; platform actions use praxis, and a bare name resolves to praxis.
(variant 1).namestringrequired; Action name; together with namespace it identifies the action. Lowercase letters, digits, dot, underscore and hyphen, up to 64 characters.
(variant 1).descriptionstringrequired; Free-text action description, at most 1000 characters.
(variant 1).labelsobjectrequired; User-defined string key and value tags for grouping and list filtering (labels[key]=value); keys must not start with praxis.
(variant 1).ownerstringrequired; Tenant that owns the action, injected by the gateway; treat it as an opaque string.
(variant 1).builtinbooleanrequired; true for platform-provided actions (namespace praxis); false for user-created actions.
(variant 1).current_revisionobjectrequired; 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.idstringrequired; 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.digeststringrequired; Content digest of the contract and implementation; an update with identical content does not create a new revision.
(variant 1).current_revision.input_schemaobjectrequired; Any JSON object whose keys are strings and whose values are any JSON value.
(variant 1).current_revision.input_schema.* (variant 5)objectRecursive JSON value.
(variant 1).current_revision.input_schema.* (variant 6)[]null / string / number / boolean / object / JSON[]Recursive JSON value.
(variant 1).current_revision.output_schemaobjectrequired; Any JSON object whose keys are strings and whose values are any JSON value.
(variant 1).current_revision.output_schema.* (variant 5)objectRecursive JSON value.
(variant 1).current_revision.output_schema.* (variant 6)[]null / string / number / boolean / object / JSON[]Recursive JSON value.
(variant 1).current_revision.errorsobject[]required; Errors the action declares it may raise, each with type, code and description.
(variant 1).current_revision.errors[].typestringrequired; Error type: a stable URI or a standard Open Workflow type such as validation, timeout, communication or runtime.
(variant 1).current_revision.errors[].codestringoptional; Optional stable error code callers can branch on.
(variant 1).current_revision.errors[].descriptionstringrequired; What this error means and when it occurs, written for callers.
(variant 1).current_revision.annotationsobjectrequired; Declared action behaviour {read_only, idempotent}; keys not supplied at creation default to false. no additional fields.
(variant 1).current_revision.annotations.read_onlybooleanrequired; true declares that the action does not change external state and only reads data.
(variant 1).current_revision.annotations.idempotentbooleanrequired; 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_msnumberrequired; 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.implementationobject / object / objectrequired; 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).sourcestringrequired; 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).imagestringrequired; Container image reference.
(variant 1).current_revision.implementation (variant 2).commandstring[]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).scriptstringrequired; 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_apisstring[]required; Platform APIs derived from the code; also the scopes of the action's run token (least privilege).
(variant 1).current_revision.created_byobjectrequired; 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.idstringrequired; 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.messagenull / stringrequired; Note supplied when this revision was created, or null.
(variant 1).current_revision.created_atstringrequired; Time this revision was created (RFC 3339 UTC).
(variant 1).stats_7dobjectrequired; 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.callsnumberrequired; Number of calls to the action over the last seven days, aggregated hourly.
(variant 1).stats_7d.failuresnumberrequired; Number of those calls that failed over the last seven days.
(variant 1).stats_7d.p50_msnull / numberrequired; 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).dependentsobjectrequired; Counts of scripts and workflows that reference the action, measured on the latest version plus drafts. no additional fields.
(variant 1).dependents.scriptsnumberrequired; Number of scripts that reference this action.
(variant 1).dependents.workflowsnumberrequired; Number of workflows that reference this action.
(variant 1).archived_atnull / stringrequired; Archive time, or null while not archived. An archived name stays reserved and cannot be reused.
(variant 1).created_atstringrequired; Creation time (RFC 3339 UTC).
(variant 1).updated_atstringrequired; Time of the last update (RFC 3339 UTC).
(variant 2) (variant 1).compatibletruerequired; Always true: the new contract is compatible with the current and five most recent revisions.
(variant 2) (variant 2).compatiblefalserequired; Always false: the new contract is incompatible with earlier revisions in at least one place.
(variant 2) (variant 2).issuesobject[]required; Every incompatibility found, each with pointer and reason.
(variant 2) (variant 2).issues[].pointerstringrequired; JSON Pointer (RFC 6901) to the incompatible location, relative to the action's input_schema or output_schema.
(variant 2) (variant 2).issues[].reasonstringrequired; Why this location is incompatible with earlier revisions (inputs may only widen, outputs may only narrow).

Measured response

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

Errors

HTTPCodes and description
400INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. INPUT_INVALID: The input does not satisfy the target contract or validation rules.
403NAMESPACE_FORBIDDEN: The namespace is read-only, or the run token does not permit this call.
404ACTION_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.
409TARGET_ARCHIVED: The target is archived and cannot be used for this operation; action execution error detail includes ns/name.
412PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match.
413PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation.
422SCHEMA_INCOMPATIBLE: The new action contract is incompatible with previous revisions.
defaultRFC 9457 automation problem. 429 includes Retry-After.

Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.

Export

On this page