Workflow Agent API

POST /api/agent/chat is a private admin endpoint used by the workflow builder's AI assistant. It is documented here for maintainers, not for third-party integrators.

Access model

The caller must satisfy all of the following:

present a valid Convex Auth bearer token
be an authenticated admin user
have the super_admin role
come from an origin allowed by ALLOWED_ORIGINS

Rate limit

20 messages per minute per authenticated user.

Request shape

The route expects JSON with:

{
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Activate workflow jx7workflow123"
        }
      ]
    }
  ],
  "currentConfig": {
    "workflowId": "jx7workflow123",
    "name": "Invoice OCR"
  }
}

messages follows the AI SDK UIMessage structure used by DefaultChatTransport.

Response model

The response is a streamed AI SDK UI message stream, not a conventional JSON document. This is the same transport expected by @ai-sdk/react.

Because the stream protocol is library-specific and internal to the admin app, Steve does not currently publish this endpoint as part of the public OpenAPI reference.

Tooling behavior

The server exposes a schema-only proposeChanges tool. It can propose a batch of workflow changes, but it never directly mutates workflows.

The admin client presents proposed changes for review and executes only the changes the user accepts. This includes activation, deactivation, deletion, form edits, and Open Loyalty schema pushes. The proposal format and client-side execution tools are internal details and should not be treated as a stable external contract.