Agents API

Async Agent ExecutionCopy Anchor Link

POST /api/v1/agents/execute

Creates an async job for supported non-chat agents. The HTTP request has a 60-second duration limit for validating and enqueueing the job; the Workflow-backed job continues asynchronously after the 202 response. Monitor it through the returned polling or stream URL.

Supported async agent IDs:

Legacy requirements, compliance, deficiency-location, report-generation, and remediation agent IDs are retired. Requests return HTTP 410; historical jobs remain readable through the Jobs API. New packet reviews use reviewed deterministic requirements rather than starting those agents.

Request BodyCopy Anchor Link

ExampleCopy Anchor Link

{
  "agentId": "procedures-discovery-agent",
  "utility": "duke-energy",
  "state": "NC",
  "userQuery": "refresh current interconnection procedure documents",
  "source": "api",
  "metadata": {
    "discoveryMode": "pda-only"
  },
  "webhookUrl": "https://partner.example/hooks/gridwonk"
}

Returns 202 with jobId, pollUrl, and streamUrl.

Streaming Chat AgentCopy Anchor Link

POST /api/v1/agents/chat

Set includeSources: true on the body to receive source events carrying the answer's citations. It defaults to false, so an existing integration's stream is unchanged — see Chat Streaming API.

SSE streaming chatbot endpoint for interactive assistant workflows. Routes through executeChatbot() for the full orchestration pipeline (classification, canonical FAQ, requirements preflight, routing). The streaming HTTP request has a 300-second duration limit.

Chat requirement lookup follows the same current-procedure behavior as the API, SDK, CLI, and MCP tools. In shadow mode (ENFORCE_CURRENT_PROCEDURE_REQUIREMENTS=false), existing displayable requirements may still be returned and logged with diagnostics. In enforcement mode (true), customer-facing chat and compliance paths only use validated requirements linked to current usable procedure documents. Deprecated, pending-review, missing-source, and hash-mismatched requirements remain review data, not customer-usable agent truth.

Request BodyCopy Anchor Link

queueProjectId is not an accepted chat-context field. Supply utility, sessionId, workContextId, or submissionId instead; requests without one of those values return INVALID_INPUT.

ExampleCopy Anchor Link

{
  "message": "What site control items are required?",
  "utility": "duke-energy",
  "state": "NC",
  "source": "cli"
}

Response TypeCopy Anchor Link

text/event-stream — Server-Sent Events with streaming chat tokens. The final complete event includes route diagnostics under chatbot when available.

NotesCopy Anchor Link

• agents/execute rejects unsupported agent IDs with a 400 error.
• procedures-discovery-agent maps to an async discovery job. It is not the same raw Agent SDK execution path as /api/agents/execute.
• Workflows requiring document access validate document ownership against API key org scope.
• /agents/chat trusts synthetic telemetry labels only in local and preview runtimes. Production derives environment/source labels server-side, and test API keys are persisted as test traffic.
• Both endpoints use withApiKeyAuth — an organization API key or OAuth bearer JWT is required.

Lightweight hosted assistanceCopy Anchor Link

POST /api/v1/assist needs the API and CLI assistant on for your organization, and returns 403 when it's off. Hosted MCP assist needs the MCP assistant. The endpoint provides one-shot text or optional streaming separately from the orchestrated chat agent. Hosted MCP assist uses the same generation service with a string prompt and optional string context; it adds no caller model or streaming control. The deployment switch, registry model resolution, organization admission and request cancellation still apply. When the default model must be resolved, a missing registry assignment fails before generation without a hardcoded fallback. See API Overview.