Automation

Validate a definition

Check source without executing it when you need diagnostics, inferred schemas or references.

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

Authentication

Authorization: Bearer $PRAXIS_API_KEY

Request fields

application/json

no additional fields.

FieldTypeDescription
kind"action" / "script" / "workflow"required; Source kind: action, script or workflow.
sourcestringrequired; Source to validate: TypeScript for action/script, YAML for workflow.

Examples

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);

Response

HTTP 200

Success

application/json

FieldTypeDescription
validbooleanrequired; Whether the source passed validation: true means it can be published or run, false means see errors.
errorsobject[]required; Validation errors, each with pointer and a Chinese detail; empty when valid is true.
errors[].pointerstringrequired; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments.
errors[].detailstringrequired; Chinese correction text saying what is wrong at this location and how to fix it.
errors[].hintstringoptional; Optional extra hint giving an actionable next step, such as using a different endpoint.
errors[].lineintegeroptional; Line number, 1-based; present only when a source location is available. minimum: 1
errors[].columnintegeroptional; Column number, 1-based; present only when a source location is available. minimum: 1
input_schemanull / objectrequired; Input JSON Schema derived from the source, or null when the source cannot be parsed.
input_schema (variant 2).* (variant 5)objectRecursive JSON value.
input_schema (variant 2).* (variant 6)[]null / string / number / boolean / object / JSON[]Recursive JSON value.
output_schemanull / objectrequired; 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)objectRecursive JSON value.
output_schema (variant 2).* (variant 6)[]null / string / number / boolean / object / JSON[]Recursive JSON value.
referencesobject[]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[].namestringrequired; Referenced item: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow.
references[].rangestringoptional; Version range or tag as written in the reference (npm rules); absent when none was written.
references[].locked_versionstringoptional; Exact version locked at publication; only script and workflow dependencies have it, actions and platform APIs are not locked.
outlinenull / object[]required; Workflow step outline; null for scripts and actions.
outline (variant 2)[].namestringrequired; Step name, the key of the step in the workflow YAML.
outline (variant 2)[].referencestringrequired; 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)[].targetstringoptional; 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)[].waitobjectoptional; Summary of a waiting step: the duration (seconds or duration) or the event type being awaited (event). no additional fields.
outline (variant 2)[].wait.untilstringoptional; 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.secondsnumberoptional; Wait in seconds when statically convertible, including duration objects and convertible ISO durations.
outline (variant 2)[].wait.eventstringoptional; Event type a listen step waits for.
outline (variant 2)[].wait.durationstringoptional; Original duration or runtime expression that cannot be statically converted to seconds.
outline (variant 2)[].loopobjectoptional; Loop information {each, in} of a for step. no additional fields.
outline (variant 2)[].loop.eachstringrequired; Loop variable name; item when not specified.
outline (variant 2)[].loop.instringrequired; Verbatim expression of the collection being iterated.
outline (variant 2)[].childrenobject[]optional; Nested child steps (inside do, fork branches, try and catch).
outline (variant 2)[].children[]objectRecursive JSON value.
warningsobject[]optional; Non-blocking script/action analysis diagnostics; an unknown type yields an empty schema and a warning. Workflow analysis may omit this field.
warnings[].pointerstringrequired; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments.
warnings[].detailstringrequired; Chinese correction text saying what is wrong at this location and how to fix it.
warnings[].hintstringoptional; Optional extra hint giving an actionable next step, such as using a different endpoint.
warnings[].lineintegeroptional; Line number, 1-based; present only when a source location is available. minimum: 1
warnings[].columnintegeroptional; Column number, 1-based; present only when a source location is available. minimum: 1
platform_apisstring[]optional; Platform API names referenced by script/action analysis, as a string array; workflow analysis may omit this field.

Measured response

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": []
}

Errors

HTTPCodes and description
400INVALID_PARAMS: Invalid request parameters, path, cursor, or body format.
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