Reference

Base URL: https://chat.app.urai.dev

Endpoints and credentials

Three credentials reach these endpoints, and the split is not the same everywhere.

Session: a signed-in person in the app.
API key: an org key, sk-urai-.... A project-scoped key reaches only workflows in its project.
Webhook secret: whsec-urai-..., sent as a bearer token or in x-urai-webhook-secret.

Method and path	Credential	Purpose
`GET /api/workflow-definitions`	Session	List the `type: workflow` definitions you can register from.
`POST /api/workflows`	Session	Register a definition with its envelope.
`GET /api/workflows`	Session	List registered workflows.
`GET /api/workflows/{id}`	Session	Read one workflow.
`PATCH /api/workflows/{id}`	Session	Edit the envelope. Omitted fields stay as they are.
`DELETE /api/workflows/{id}`	Session	Disable the workflow. The run history stays.
`GET /api/workflows/{id}/triggers`	Session	List triggers.
`POST /api/workflows/{id}/triggers`	Session	Create a trigger. Returns the secret one time.
`POST /api/workflows/{id}/triggers/{trigger_id}/rotate`	Session	Issue a new secret and stop the old one.
`DELETE /api/workflows/{id}/triggers/{trigger_id}`	Session	Delete a trigger that never ran, otherwise disable it.
`GET /api/workflows/{id}/runs`	Session	Run history for one workflow.
`POST /api/workflows/{id}/runs`	Session or API key	Start a run. No trigger, so no default arguments.
`GET /api/workflows/runs/{run_id}`	Session or API key	Run status and result.
`GET /api/workflows/runs/{run_id}/approvals`	Session or API key	What the run waits on, or waited on.
`POST /api/workflows/approvals/{approval_id}/decision`	Session or API key	Approve or reject, resuming the run.
`POST /api/workflows/runs/{run_id}/cancel`	Session	Stop further ticks. A step already running is not interrupted.
`POST /api/workflows/hooks/{hook_token}`	Webhook secret	Start a run. Returns `202` and a `status_url`.
`GET /api/workflows/hooks/{hook_token}/runs/{run_id}`	Webhook secret	Poll a run this trigger started.

Registering, editing, managing triggers, and cancelling need a person. An org API key cannot do them. A webhook secret starts runs and polls them, and reaches nothing else.

Workflow object

Field	Notes
`name`	Required.
`description`	Optional free text.
`project_id`	Optional. Without it the workflow belongs to the organization.
`uraijs_tool_id`	Required. The definition, from `GET /api/workflow-definitions`.
`object_type`	Required. The exported `@PersistentObject` class to start.
`allowed_secrets`	Names that `secrets.get()` resolves. Any other name fails the step.
`net_allowlist`	Hosts the code reaches. Recorded and carried to the runtime.
`allow_chat`	Gates `urai:chat`.
`knowledge_collections`	Knowledge collections the code may read through `urai:knowledge`, by slug or id. Empty grants nothing.
`default_run_as_user_id`	Whose integration connections a run reaches. Empty means org-shared connections only.
`disabled_at`	Set by `DELETE`. A disabled workflow starts no runs.

Trigger object

Field	Notes
`name`	Your label for the trigger.
`kind`	`webhook`. It is the only kind, and you can omit it on create.
`hook_token`	The public URL segment. Not a credential on its own.
`default_args`	Merged under the caller’s payload. The caller wins on a conflict.
`run_as_user_id`	Overrides the workflow default for runs this trigger starts.
`used`	Present when listing. `true` once the trigger has started a run.
`disabled_at`	Set when a used trigger is removed.

The secret appears once, in the reply that creates or rotates the trigger. Urai stores only its hash.

Run object

Field	Notes
`id`	The run id.
`workflow_id` · `trigger_id`	`trigger_id` is null for a direct start.
`uraijs_instance_id`	The runtime instance.
`status`	See the table below.
`run_as_user_id`	The identity the run acts as, if any.
`external_user_id`	From `x-urai-external-user`. Attribution only.
`started_by`	The person who started it, if any.
`input`	The merged arguments.
`result`	What `complete()` returned. Null until the run finishes.
`error`	The failure reason. Null unless the run failed.
`created_at` · `updated_at` · `completed_at`	Timestamps.

The webhook polling endpoint returns a narrower object: run_id, status, result, error, external_user_id, created_at, and completed_at.

Status	Meaning
`pending`	Created, not started.
`running`	Working, or waiting on a person.
`completed`	The workflow called `complete()`.
`failed`	A step failed with no attempts left.
`cancelled`	Someone stopped it.

Approval object

Field	Notes
`id`	Use this to decide it.
`run_id`	The run it belongs to.
`name`	The name your workflow passed.
`request`	The object your workflow passed. The approver sees it.
`status`	`awaiting` or `decided`.
`decision`	Null until decided, then the full decision.
`decided_by`	Opaque reference to whatever recorded it.
`created_at` · `decided_at`	`decided_at` is null while awaiting.

Decision request body:

Field	Required	Notes
`approved`	yes	`true` or `false`. Both resume the run.
`comment`	no	Free text, given to the workflow.
`data`	no	Arbitrary JSON, arrives as `decision.data`.

A second decision on the same approval returns 409.

The urai:workers API

import { Workflow, Step } from "urai:workers";

Member	Signature	Notes
`registerStep`	`(name, StepClass, opts?) => StepRef`	Call it in the constructor. `opts` is the retry policy.
`runStep`	`(step, args?) => { result }`	Memoized. Suspends the tick when the step has not finished.
`runStepMany`	`(step, argsList) => { results }`	Fan-out. Results align to the input list. Each pair is memoized on its own.
`awaitApproval`	`(name, request?) => ApprovalDecision`	Parks the run until a person decides.
`complete`	`(result) => void`	Finishes the workflow.
`completeStep`	`(result) => void`	Called inside a step to record its output.

Never wrap runStep, runStepMany, awaitApproval, or complete in try/catch.

Retry options, passed to registerStep:

Option	Type	Default
`retries`	number	`0`. Attempts after the first one.
`backoff`	`"fixed"`, `"linear"`, `"exponential"`	`"fixed"`
`delayMs`	number	`1000`. Every strategy waits this before the first retry.

Decision returned by awaitApproval:

Field	Type
`approved`	boolean
`approver`	string or null
`decidedBy`	string or null
`comment`	string or null
`data`	unknown
`decidedAt`	string, ISO-8601

Runtime modules

Import	Use
`urai:workers`	`Workflow` and `Step`.
`urai:persistence`	The `@PersistentObject` decorator.
`urai:secrets`	`await secrets.get(name)`. Resolves through the host each call.
`urai:chat`	`extract()` for a schema-constrained object, `chat()` for text. Needs chat access.
`urai:knowledge`	`knowledge.list()`, `knowledge.open()`, and the reads on a document. Needs granted collections. See Read documents from code.
`urai:lib/<org>/<name>`	Your published libraries.

CLI commands

Command	Purpose
`uraijs init <name> --type workflow`	Scaffold a workflow project.
`uraijs workflow run <Class> -a '{...}'`	Drive an instance to completion. State persists to `.urai/workflows.json`.
`uraijs workflow run <Class> --id <id>`	Resume an interrupted instance. Finished steps are not run again.
`uraijs workflow approve --id <id> --name <name>`	Decide an approval a local run waits on. Add `--reject` for the other branch.
`uraijs workflow list`	List local instances and their status.
`uraijs types`	Refresh `urai.d.ts` and `tsconfig.json`.
`uraijs secrets detect`	List the secrets the code reads.

Useful flags on workflow run and workflow approve:

Flag	Purpose
`--secrets-file <path>` · `-s '{...}'`	Local secret values.
`--vars-file <path>` · `-v '{...}'`	Local variables.
`--script <path>`	Override `[project].main` from `urai.toml`.
`--store <path>`	Override the local state store.
`--json`	Machine-readable output.