6. The API

Access

All endpoints are under /api/ and are published through API Management, called the gateway. The gateway checks the caller's Entra token and role before the engine sees the request. Page 15 lists the roles. The engine's controllers hold no logic; each endpoint calls one service method.

Endpoints

Metadata endpoints

Callers: the pipeline, developers.

Endpoint	Action
POST /api/metadata/workflow	Register a definition. Rejects on failed checks.
PUT /api/metadata/workflow	Register several.
GET /api/metadata/workflow/{name}?version=	Read one. Latest version when omitted.
GET /api/metadata/workflow	List all.
DELETE /api/metadata/workflow/{name}/{version}	Remove a version. Rejected if runs exist.
POST, PUT, GET, DELETE /api/metadata/taskdefs	The same for task definitions.
POST, GET /api/metadata/instructions	Register and read instruction texts.

Workflow endpoints

Callers: applications, operators, the pipeline, the UI.

Endpoint	Action
POST /api/workflow/{name}	Start a run. Body below. Returns the run id.
GET /api/workflow/{id}	The run with all tasks, inputs, outputs. Reads the archive for old runs.
GET /api/workflow/{id}/status	Status only.
GET /api/workflow/search?name=&status=&from=&to=&correlationId=&freeText=	Search runs.
GET /api/workflow/{name}/correlated/{correlationId}	Runs sharing a correlation id.
PUT /api/workflow/{id}/pause, .../resume	Pause and resume.
DELETE /api/workflow/{id}?reason=	Terminate.
POST /api/workflow/{id}/retry, .../restart, .../rerun	Page 13.
PUT /api/workflow/{id}/skiptask/{ref}	Skip a task with a given output.
POST /api/workflow/{id}/messages	Send a message to a running run.
POST /api/workflow/{id}/signal	Send a message and wake the run.
POST /api/workflow/test	Run a definition with mocked task outputs. Used in the pipeline.
PUT, POST /api/workflow/bulk/{pause, resume, restart, retry, terminate}	The same operation over a list of ids.

Start request body:

{ "name": "engagement_approval", "version": 3,
  "input": { "engagement_id": 42 },
  "correlationId": "engagement-42",
  "priority": 50,
  "taskToDomain": { "parse_pdf": "au" },
  "idempotencyKey": "engagement-42-approval",
  "idempotencyStrategy": "RETURN_EXISTING" }

Field	Meaning
version	Optional. Latest when omitted.
correlationId	Your own id for finding runs later.
priority	0 to 99. Copied to worker queue messages.
taskToDomain	Routes named task types to a domain's worker pool. * applies to all. Page 9.
idempotencyKey, idempotencyStrategy	With FAIL, a second start with the same key returns 409. With RETURN_EXISTING, it returns the first run's id.

Task endpoints

Callers: workers, the Teams bridge, external systems.

Endpoint	Action
GET /api/tasks/poll/{type}?workerId=&domain=	Take one waiting task. 204 when none.
GET /api/tasks/poll/batch/{type}?count=&timeout=	Take up to count; waits up to timeout ms, maximum 5000.
POST /api/tasks	Post a result. Body: {taskId, workflowId, status, outputData, logs, callbackAfterSeconds}.
POST /api/tasks/{workflowId}/{ref}/{status}	Complete a task by name. Body becomes the output. Used for HUMAN and WAIT.
POST /api/tasks/{taskId}/log	Append a log line.
GET /api/tasks/{taskId}	Read a task.
GET /api/tasks/search	Search tasks.
GET /api/tasks/queue/sizes	Waiting and dead-lettered counts per queue.
GET /api/tasks/queue/polldata?taskType=	Last poll time per worker, to see whether a type has a live worker.
GET /api/tasks/external-storage-location	A short-lived upload URL for large outputs.

Event and schedule endpoints

Callers: the pipeline, operators.

Endpoint	Action
POST, PUT, GET, DELETE /api/event	Manage event handlers. Page 11.
GET /api/event/executions?handler=	What each handler did with each message.
POST, PUT, GET, DELETE /api/schedule	Manage schedules. Page 11.

Admin endpoints

Callers: operators, monitoring.

Endpoint	Action
GET /health	Checks Azure SQL, Durable Task Scheduler, Service Bus, Blob.
GET /api/admin/config	Non-secret settings.
GET /api/admin/env	Non-secret configuration keys.
GET /api/admin/queues	Active, scheduled, and dead-lettered counts per queue.
POST /api/admin/requeue/{type}	Move dead-lettered messages back to the queue.
POST /api/admin/repair/{id}	Re-queue a run's open worker tasks.