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 may execute direct workflow actions, including:

activating workflows
deactivating workflows
deleting workflows after explicit confirmation
pushing Open Loyalty schemas

Form-editing tools are applied client-side by the admin app and should not be treated as a stable external contract.