API Reference

API reference for agent execution, workflows, schedules, chats, and human review

This reference documents the Supervity APIs used to programmatically interact with the platform.

These APIs allow you to:

execute AI agents and workflows
monitor execution runs and schedules
interact with agents via chat and streaming
embed human-in-command approval flows
access execution artifacts such as logs, forms, and attachments

If you are coming from Key Features → API & Webhooks, this is the canonical technical contract.

API Model Overview

Supervity exposes an agent-driven execution model.

Core objects you interact with via APIs:

Agent — plans and governs execution
Workflow — executable representation of the plan
Run — a single execution of a workflow
Human review form — approval or input checkpoint
Chat thread — conversational and streaming interaction
Object — files and attachments used during execution

Most APIs are used to trigger, observe, or govern execution.

Base URL & Authentication

Base URL

All endpoints are relative to your workflow service base URL. Set the

text

environment variable (e.g. in your

text

or deployment config):

bash

Use this variable in the examples below (or substitute the URL directly).

Authentication

All requests require a bearer token.

bash

Include the token in every request:

bash

Tokens control:

which workflows can be executed
which runs can be inspected
which approvals can be acted upon

API Conventions

Pagination

List endpoints typically support:

text
(default: 1)
text
(endpoint-specific)

Content Types

JSON APIs Use
text
Execution & Streaming APIs Use
text
(via
text
)

Workflow & Agent Management APIs

These APIs are used to inspect and manage agent-generated workflows.

List workflows

GET

text

Query params:

text
text
text
(optional)

bash

Get workflow by ID

GET

text

bash

Delete workflow

DELETE

text

bash

Deleting a workflow does not affect past runs or audit history.

Scheduling APIs

Scheduling controls when workflows execute, not how they behave.

List schedules

GET

text

Used to list all schedules (e.g. for the Schedule page). Supports pagination and optional org/team context.

Headers:

json

text

,

text

, and

text

are optional; omit them to use default context.

Query params:

text
(default: 1)
text
(default: 20)

Example response:

json

cURL example:

bash

Pause or resume a schedule

PUT

text

Headers:

json

Request body (JSON):

json

Set

text

to

text

to pause the schedule,

text

to resume.

cURL example:

bash

Delete a schedule

DELETE

text

Headers:

json

This removes the schedule but keeps the workflow intact.

cURL example:

bash

Parse a natural-language schedule

POST

text

Headers:

json

Request body (JSON):

json

Returns a normalized schedule expression.

cURL example:

bash

Get upcoming scheduled runs

GET

text

Returns the list of upcoming run times for a workflow’s schedule.

Headers:

json

cURL example:

bash

Execution & Run APIs

Runs represent individual executions of an agent workflow.

List workflow runs

GET

text

Common query params:

text
text
text
text

Get workflow run by ID

GET

text

Returns:

run status
step-level activity runs
inputs and outputs
error context (if any)

Cancel workflow runs

POST

text

Body can include:

text
(cancel active runs)
or
text
(cancel specific runs)

Dashboard counts per workflow

GET

text

Used for UI dashboards and monitoring systems.

Execute a workflow (agent execution)

POST

text

This endpoint triggers agent-backed execution.

multipart/form-data fields:

text
(required)
text
text
(optional execution overrides)

Example:

bash

Execution always respects:

approval gates
permissions
human-in-command policies

Chat & Streaming APIs (Agent Interaction)

These APIs support conversational and streaming interaction with agents.

Create a chat thread

POST

text

Response:

json

Stream messages to an agent (SSE)

POST

text

Used for:

conversational interaction
planner visibility
streaming execution updates
human-in-command interrupts

Common stream event types:

text
text
text
text
text
text
text

Human Review APIs (Human-in-Command)

These APIs allow external systems to participate in approval flows (e.g. Human Review page to list approvals, User Form page to view and act on a single approval).

List pending review forms (approvals)

GET

text

Used to list pending approvals for the Human Review / workbench page.

Headers:

json

Query params:

text
(default: 1)
text
(default: 20)
text
(optional)

Example response:

json

cURL example:

bash

With optional search:

bash

Fetch a rendered review form (view approval)

GET

text

Used to load a single approval form for the User Form page (view and submit the approval).

Headers:

json

No request body.

Example response:

json

You can render the provided

text

directly or build a custom UI from

text

. Submitting the form (see submit endpoint) resumes execution.

cURL example:

bash

Submit a review decision

POST

text

Headers:

json

Request body (JSON):

json

cURL example:

bash

Submitting a form resumes execution automatically.

Objects & Attachments

Objects represent files exchanged during execution.

Download an attachment

GET

text

Query params:

text
text
(e.g.
text
)

Notes on Extensibility

Depending on deployment, Supervity may also expose APIs for:

registering external tools
integrating custom services
advanced policy or governance controls

These are documented in dedicated reference sections when enabled.

Where to Go Next

understand execution → Workflows Explained
see agents in action → Examples
add governance → Human Review & Approvals

These APIs let you embed Supervity agents into your systems while preserving control, observability, and human oversight.