HTTP reference for operators, builders, and integrators

PilotWeave API Reference

User-facing reference for the HTTP endpoints that power workflow design, supervised execution, integrations, auth, and billing in PilotWeave.

Standard Write Headers
x-idempotency-key
x-actor-type
x-actor-id
x-request-id
x-organization-id
x-user-id
  • Unless marked Public or Admin, endpoints require an authenticated workspace session.
  • Write routes use the normalized error envelope and may return request metadata when provided.
  • Path params use colon notation here for readability, for example :workflowId or :runId.
Workflows

Workflows

Create workflows, manage draft and published state, edit graph structure, and control launch policies.

GETAuthenticated
/api/workflows

List workflows in the current organization.

POSTAuthenticated
/api/workflows

Create a workflow, optionally from a template.

Request Body
  • name
  • objective?
  • trigger?
  • templateId?
  • template?
GETAuthenticated
/api/workflows/:workflowId

Fetch workflow metadata by id.

PATCHAuthenticated
/api/workflows/:workflowId

Rename or update workflow metadata.

Request Body
  • name
  • objective?
  • trigger?
DELETEAuthenticated
/api/workflows/:workflowId

Delete a workflow that is not the built-in demo workflow.

GETAuthenticated
/api/workflows/:workflowId/draft

Get the current workflow draft payload.

POSTAuthenticated
/api/workflows/:workflowId/draft

Save the current workflow draft payload.

Notes
  • Supports idempotency headers on write requests.
POSTAuthenticated
/api/workflows/:workflowId/validate

Run server-side validation against the draft graph.

POSTAuthenticated
/api/workflows/:workflowId/steps

Create a step in the draft graph.

Request Body
  • kind
PATCHAuthenticated
/api/workflows/:workflowId/steps/:stepId

Update one step in the draft graph.

Request Body
  • title?
  • summary?
  • owner?
  • risk?
  • agentId?
  • mcpConnectionId?
  • mcpToolNames?
DELETEAuthenticated
/api/workflows/:workflowId/steps/:stepId

Delete one step from the draft graph.

POSTAuthenticated
/api/workflows/:workflowId/edges

Create a connection between two nodes.

Request Body
  • source
  • target
DELETEAuthenticated
/api/workflows/:workflowId/edges

Delete a connection between two nodes.

Request Body
  • source
  • target
GETAuthenticated
/api/workflows/:workflowId/diff

Compare current draft to the latest published version.

GETAuthenticated
/api/workflows/:workflowId/publish-review

Return the pre-publish review summary used by UI and agents.

POSTAuthenticated
/api/workflows/:workflowId/publish

Publish the current launchable draft as an immutable version.

Notes
  • Returns 400 when validation blockers remain.
GETAuthenticated
/api/workflows/:workflowId/published/latest

Fetch the latest published workflow payload.

GETAuthenticated
/api/workflows/:workflowId/guardrails

Get provider and run guardrails for the workflow.

PUTAuthenticated
/api/workflows/:workflowId/guardrails

Update provider and run guardrails for the workflow.

Request Body
  • allowedProviders
  • maxToolCalls
  • maxRunDurationSeconds
  • requireApprovalForHighRiskLive
GETAuthenticated
/api/workflows/:workflowId/policies

List workflow tool-policy rules.

PUTAuthenticated
/api/workflows/:workflowId/policies

Replace workflow tool-policy rules.

Request Body
  • Array<{ id, toolName, outcome, reason, risk?, priority? }>
GETAuthenticated
/api/workflows/:workflowId/autonomy

Get workflow autonomy settings.

PUTAuthenticated
/api/workflows/:workflowId/autonomy

Update workflow autonomy settings.

Request Body
  • mode
  • maxAutonomousActionsPerRun
  • maxAutonomousHighRiskActionsPerRun
  • escalationThreshold
GETAuthenticated
/api/workflows/:workflowId/budget

Get budget thresholds for workflow execution.

PUTAuthenticated
/api/workflows/:workflowId/budget

Update budget thresholds for workflow execution.

Request Body
  • maxEstimatedRunCostUsd
  • maxEstimatedToolCostUsd
GETAuthenticated
/api/workflows/:workflowId/compensation

Get compensation and rollback policy.

PUTAuthenticated
/api/workflows/:workflowId/compensation

Update compensation and rollback policy.

Request Body
  • enabled
  • commands
  • maxCompensationActionsPerRun
GETAuthenticated
/api/workflows/:workflowId/metrics

Get workflow run metrics and cost rollups.

Runs And Operations

Runs And Operations

Simulate, launch, inspect, replay, and operationally manage workflow runs and approval paths.

POSTAuthenticated
/api/workflows/:workflowId/simulate

Run a simulation from the current draft.

Notes
  • Supports idempotency headers on write requests.
POSTAuthenticated
/api/workflows/:workflowId/run

Run the latest published workflow in production mode.

Notes
  • Returns 409 if no published version exists.
GETAuthenticated
/api/workflows/:workflowId/runs

List recent workflow runs.

Query Params
  • mode?
  • status?
  • limit?
GETAuthenticated
/api/workflows/:workflowId/runs/latest

Fetch the latest run for the workflow.

GETAuthenticated
/api/workflows/:workflowId/runs/:runId

Fetch one run with trace details.

Query Params
  • includeEvents?
GETAuthenticated
/api/workflows/:workflowId/runs/:runId/events

List or filter audit events for one run.

Query Params
  • eventType?
  • nodeId?
  • limit?
POSTAuthenticated
/api/workflows/:workflowId/runs/:runId/replay

Replay a prior simulation or production run.

Request Body
  • reason
  • compensation?
  • override?
POSTAuthenticated
/api/approvals/:approvalId/decision

Approve or reject a pending approval.

Request Body
  • status
  • note?
GETAuthenticated
/api/overrides

List replay override events and acknowledgement metrics.

Query Params
  • workflowId?
  • limit?
GETAuthenticated
/api/overrides/:auditEventId

Fetch one replay override entry.

POSTAuthenticated
/api/overrides/:auditEventId/acknowledge

Acknowledge an override event for follow-up.

Request Body
  • note?
GETAuthenticated
/api/workflows/:workflowId/tasks

List tasks for the workflow.

POSTAuthenticated
/api/workflows/:workflowId/tasks

Create a task for operator-driven execution work.

Request Body
  • goal
  • successCriteria
  • priority?
GETAuthenticated
/api/workflows/:workflowId/tasks/:taskId

Fetch one task.

PATCHAuthenticated
/api/workflows/:workflowId/tasks/:taskId

Update task status, owner, and policy outcome.

Request Body
  • status
  • assignedTo?
  • policyDecision?
POSTAuthenticated
/api/workflows/:workflowId/tasks/:taskId/evaluate

Pre-flight a tool action against policy before execution.

Request Body
  • nodeId?
  • mcpConnectionId
  • toolName
  • toolArgs?
GETAuthenticated
/api/escalations

List currently escalated tasks.

Copilot

Copilot

Review copilot history, chat with the workflow copilot, and apply or roll back proposed changes.

GETAuthenticated
/api/workflows/:workflowId/copilot/history

List recent copilot history entries.

Query Params
  • limit?
POSTAuthenticated
/api/workflows/:workflowId/copilot/chat

Send a copilot chat prompt for workflow assistance.

POSTAuthenticated
/api/workflows/:workflowId/copilot/apply

Apply a structured copilot action to the workflow draft.

POSTAuthenticated
/api/workflows/:workflowId/copilot/rollback

Roll back the latest applied copilot mutation.

Agents, Rules, Templates, And Tools

Agents, Rules, Templates, And Tools

Manage imported agents, reusable rule packs, workflow templates, and tool discovery surfaces.

GETAuthenticated
/api/agents

List imported agents.

POSTAuthenticated
/api/agents

Create an imported agent entry.

Request Body
  • name
  • provider
  • description?
PATCHAuthenticated
/api/agents/:agentId

Update imported agent configuration.

Request Body
  • name?
  • provider?
  • description?
  • directive?
  • model?
  • credentialLabel?
  • rulePackIds?
  • status?
POSTAuthenticated
/api/agents/import

Import an agent definition from markdown.

Request Body
  • markdown
GETAuthenticated
/api/rules

List rule packs.

POSTAuthenticated
/api/rules

Create a rule pack.

Request Body
  • name
  • scope
  • markdown
PATCHAuthenticated
/api/rules/:rulePackId

Update a rule pack.

DELETEAuthenticated
/api/rules/:rulePackId

Delete a rule pack.

GETAuthenticated
/api/workflow-templates

List built-in workflow templates.

POSTAuthenticated
/api/workflow-templates/import

Validate and import a shared workflow template payload.

Request Body
  • template
GETAuthenticated
/api/tools

List tool catalog entries visible in the workspace.

Triggers

Triggers

Configure workflow triggers and accept external or manual trigger-driven launches.

GETAuthenticated
/api/workflows/:workflowId/triggers

List workflow trigger definitions.

PUTAuthenticated
/api/workflows/:workflowId/triggers

Replace workflow trigger definitions.

Request Body
  • Array<{ enabled, sourceType, sourceName, auth, idempotency?, guardrails?, schedule? }>
POSTPublic
/api/triggers/:triggerId/ingest

Accept an external trigger event and queue a simulation run.

Notes
  • Validates trigger-level auth, rate limits, payload size, and idempotency.
POSTAuthenticated
/api/triggers/:triggerId/run

Start a manual-trigger run for an authenticated user.

Credentials And Connected Accounts

Credentials And Connected Accounts

Manage BYOK provider credentials, runtime settings, provider testing, and connected third-party accounts.

GETAuthenticated
/api/credentials/providers

List masked provider credentials for the organization.

POSTAuthenticated
/api/credentials/providers

Create or update a provider credential.

Request Body
  • provider
  • label
  • apiKey
DELETEAuthenticated
/api/credentials/providers/:credentialId

Delete one provider credential.

GETAuthenticated
/api/credentials/providers/readiness

Check credential readiness for agent-bound workflow steps.

Query Params
  • workflowId
GETAuthenticated
/api/credentials/providers/settings

List provider runtime settings such as mock or live mode.

PATCHAuthenticated
/api/credentials/providers/settings

Update a provider runtime setting.

Request Body
  • credentialId
  • mode
POSTAuthenticated
/api/credentials/providers/test

Test a provider credential or provider configuration path.

GETAuthenticated
/api/connected-accounts

List connected provider accounts for the organization.

DELETEAuthenticated
/api/connected-accounts/:accountId

Disconnect one linked account.

GETAuthenticated
/api/connected-accounts/settings

Get managed OAuth app settings for supported providers.

PATCHAuthenticated
/api/connected-accounts/settings

Create or update managed OAuth app settings.

Request Body
  • provider
  • clientId
  • clientSecret?
  • redirectUri
POSTAuthenticated
/api/connected-accounts/google/start

Start Google OAuth account-linking flow.

GETAuthenticated
/api/connected-accounts/google/callback

Handle Google OAuth callback and finalize linking.

POSTAuthenticated
/api/connected-accounts/slack/start

Start Slack OAuth account-linking flow.

GETAuthenticated
/api/connected-accounts/slack/callback

Handle Slack OAuth callback and finalize linking.

MCP Connections

MCP Connections

Create, test, and catalog MCP connections used by workflow steps and tool exposure.

GETAuthenticated
/api/mcp/connections

List MCP connections.

POSTAuthenticated
/api/mcp/connections

Create an MCP connection.

Request Body
  • name
  • transport
  • url
  • authType?
  • allowedTools?
POSTAuthenticated
/api/mcp/connections/:connectionId/test

Test whether one MCP connection is reachable.

GETAuthenticated
/api/mcp/connections/:connectionId/catalog

Fetch the stored tool catalog for one MCP connection.

POSTAuthenticated
/api/mcp/connections/:connectionId/catalog

Sync or persist tool catalog entries for one MCP connection.

Request Body
  • tools?
Scorecards

Scorecards

Measure workflow spend and maintain anomaly thresholds for budget-oriented monitoring.

GETAuthenticated
/api/workflows/:workflowId/scorecards/spend

Get spend scorecard metrics and anomaly flags.

Query Params
  • days?
GETAuthenticated
/api/workflows/:workflowId/scorecards/thresholds

Get spend-scorecard thresholds.

PUTAuthenticated
/api/workflows/:workflowId/scorecards/thresholds

Update spend-scorecard thresholds.

Request Body
  • runCostSpikeMultiplier
  • toolCostSpikeMultiplier
  • budgetBlockRateThreshold
Authentication And Beta Access

Authentication And Beta Access

Public entry points for signup and login plus admin beta-queue APIs and session lifecycle endpoints.

POSTPublic
/api/beta-access/request

Submit a public beta-access request.

Request Body
  • name
  • email
  • company
  • useCase
  • sourcePath
GETAdmin
/api/beta-access/requests

List beta-access requests for admin review.

POSTAdmin
/api/beta-access/requests/:requestId/decision

Approve or reject a beta-access request.

Request Body
  • decision
  • email?
  • accessLevel?
  • reviewNotes?
POSTPublic
/api/auth/login

Authenticate a user and set the session cookie.

Request Body
  • email
  • password
POSTPublic
/api/auth/signup

Create an account, optionally using an invite token.

Request Body
  • email
  • password
  • inviteToken?
POSTAuthenticated
/api/auth/logout

Clear the session cookie.

GETPublic
/api/auth/session

Validate the current session cookie.

POSTPublic
/api/auth/password-reset/request

Request a password reset email.

Request Body
  • email
POSTPublic
/api/auth/password-reset/complete

Complete a password reset and establish a new session.

Request Body
  • accessToken
  • password
Billing

Billing

Create checkout and portal sessions, inspect current usage, and receive subscription lifecycle webhooks.

POSTAuthenticated
/api/billing/checkout

Create a checkout session for a plan upgrade.

Request Body
  • planCode
  • successUrl
  • cancelUrl
POSTAuthenticated
/api/billing/portal

Create a billing-portal session.

Request Body
  • returnUrl
GETAuthenticated
/api/billing/usage

Get subscription and usage metrics for the workspace.

GETAuthenticated
/api/billing/readiness

Check billing configuration readiness.

POSTPublic
/api/billing/webhook

Process external billing lifecycle events idempotently.

Notes
  • Stripe and mock-billing webhook modes are both supported.