Workflows
11 operations. {prefix} is the route prefix passed to
MapAgentPrism; the template uses /agentprism.
GET {prefix}/api/workflows
Section titled “GET {prefix}/api/workflows”Operation ID: AgentPrismListWorkflows
Lists workflows defined in code and stored in the database.
What the list contains depends on whether the workflow engine is registered. With the engine, both code-defined and stored workflows appear, because only the engine can see the ones built in code. Without it, only stored definitions are listed — managing definitions does not require the engine, but running them does.
Authorization: bearer authentication; Reader role policy when that policy is registered; WorkflowsRead API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of WorkflowDescriptor |
— |
GET {prefix}/api/workflows/{name}
Section titled “GET {prefix}/api/workflows/{name}”Operation ID: AgentPrismGetWorkflow
Returns a single workflow definition.
Only stored definitions are editable and only they are returned here. A code-defined workflow is listed and can be run but has no stored definition, so it answers 404 with a distinct ‘No editable definition’ title — different from the plain not-found title used for a name that does not exist at all. Read the structure of a code-defined workflow from the graph endpoint instead.
Authorization: bearer authentication; Reader role policy when that policy is registered; WorkflowsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → WorkflowDefinition |
— |
PUT {prefix}/api/workflows/{name}
Section titled “PUT {prefix}/api/workflows/{name}”Operation ID: AgentPrismSaveWorkflow
Creates or updates a workflow definition.
The definition is validated at save time with the same rules the compiler applies, so a shape that could not run is rejected with 400 instead of failing on the first run. Which fields are required depends on the kind — a manager driven workflow needs its manager agent, for example. The call replaces the whole definition: omitted fields are cleared, not merged. The name comes from the path and is not taken from the body.
Authorization: bearer authentication; Admin role policy when that policy is registered; WorkflowsAdmin API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
Request body (required):
application/json→WorkflowSaveRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → WorkflowDefinition |
— |
DELETE {prefix}/api/workflows/{name}
Section titled “DELETE {prefix}/api/workflows/{name}”Operation ID: AgentPrismDeleteWorkflow
Deletes a workflow definition.
Only a stored definition can be deleted; a code-defined workflow is removed by changing the application, and asking for one here returns 404. Runs and checkpoints already recorded are kept, so past executions stay readable, but a checkpoint cannot be resumed once the definition it needs is gone.
Authorization: bearer authentication; Admin role policy when that policy is registered; WorkflowsAdmin API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
| Response | Body | Headers |
|---|---|---|
| 204 No Content | — | — |
GET {prefix}/api/workflows/{name}/graph
Section titled “GET {prefix}/api/workflows/{name}/graph”Operation ID: AgentPrismGetWorkflowGraph
Returns the compiled graph of the workflow.
Node IDs are identical to the executor IDs in run events; this is how the UI colors nodes live. The response also carries the Mermaid text generated by Microsoft Agent Framework.
Authorization: bearer authentication; Reader role policy when that policy is registered; WorkflowsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → WorkflowGraph |
— |
POST {prefix}/api/workflows/{name}/run
Section titled “POST {prefix}/api/workflows/{name}/run”Operation ID: AgentPrismRunWorkflow
Runs the workflow and streams its events over SSE.
Each frame carries a RunEvent. The first frame reports the run ID; every agent invoked within the workflow opens its own runs row, viewable as a tree via GET /api/runs/{runId}/tree.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
name |
path | yes | string |
— |
Request body (optional):
application/json→WorkflowRunHttpRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | text/event-stream → string |
— |
| 404 Not Found | application/problem+json → ProblemDetails |
— |
| 429 Too Many Requests | application/problem+json → ProblemDetails |
— |
| 501 Not Implemented | application/problem+json → ProblemDetails |
— |
GET {prefix}/api/workflows/functions
Section titled “GET {prefix}/api/workflows/functions”Operation ID: AgentPrismListWorkflowFunctions
Lists function nodes registered in code.
Function nodes are defined only in code, with AddWorkflowFunction - the same code-only boundary AddTool draws for tools. This endpoint does not offer a write path; the UI lets users pick from this list when building a Sequential workflow’s node list. An empty list means no function was registered, or the workflow engine was never turned on with UseWorkflows - either way, existing agent-only workflows are unaffected.
Authorization: bearer authentication; Reader role policy when that policy is registered; WorkflowsRead API-key scope.
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of WorkflowFunctionResponse |
— |
GET {prefix}/api/workflows/runs/{runId}/checkpoints
Section titled “GET {prefix}/api/workflows/runs/{runId}/checkpoints”Operation ID: AgentPrismListWorkflowCheckpoints
Lists the checkpoints of a workflow run.
Checkpoints are the points a run can be resumed from; each entry’s id is what the resume endpoint takes. A run belonging to another tenant is reported as 404 rather than 403, so the API does not confirm that it exists. An empty list means the run wrote no checkpoint — checkpointing is a property of how the workflow was built, not something this endpoint can turn on. Checkpoints are subject to retention, so an old run may have none left.
Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
runId |
path | yes | string (uuid) |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of WorkflowCheckpointRecord |
— |
GET {prefix}/api/workflows/runs/{runId}/requests
Section titled “GET {prefix}/api/workflows/runs/{runId}/requests”Operation ID: AgentPrismListWorkflowRequests
Lists a run’s pending human input requests.
Only a run in the ‘AwaitingInput’ state returns requests. Requests are read from the run’s event stream; there is no separate table.
Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
runId |
path | yes | string (uuid) |
— |
| Response | Body | Headers |
|---|---|---|
| 200 OK | application/json → array of WorkflowPendingRequest |
— |
POST {prefix}/api/workflows/runs/{runId}/respond
Section titled “POST {prefix}/api/workflows/runs/{runId}/respond”Operation ID: AgentPrismRespondWorkflowRequest
Responds to a pending request and resumes the run.
The response is matched to the request re-published with the same ID in the execution resumed from the checkpoint. Resuming opens a NEW runs row; events stream over SSE.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
runId |
path | yes | string (uuid) |
— |
Request body (optional):
application/json→WorkflowRespondHttpRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | text/event-stream → string |
— |
| 400 Bad Request | application/problem+json → ProblemDetails |
— |
| 501 Not Implemented | application/problem+json → ProblemDetails |
— |
POST {prefix}/api/workflows/runs/{runId}/resume
Section titled “POST {prefix}/api/workflows/runs/{runId}/resume”Operation ID: AgentPrismResumeWorkflow
Resumes from a checkpoint and streams events over SSE.
Resuming opens a NEW run rather than continuing the old one: the original run row is never rewritten, and the first streamed frame reports the new run id. The body is optional — without a checkpoint id the run resumes from its latest checkpoint. The engine must be registered; otherwise the response is 501. Because the status code is sent before the stream begins, a failure after that point arrives as an SSE error frame rather than an HTTP error.
Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.
| Parameter | In | Required | Type | Description and rules |
|---|---|---|---|---|
runId |
path | yes | string (uuid) |
— |
Request body (optional):
application/json→WorkflowResumeHttpRequest
| Response | Body | Headers |
|---|---|---|
| 200 OK | text/event-stream → string |
— |
| 501 Not Implemented | application/problem+json → ProblemDetails |
— |