Skip to main content
Assistant providers are AI backends that OpenIndex uses to execute agent-required workflow stages. When a workflow stage is marked as agent-required, OpenIndex dispatches that stage to a configured provider instead of waiting for a human to act. Instance admins configure providers for the entire deployment. Individual workflow stage settings reference the active provider configuration by ID.
Workflow agent run tokens cannot manage provider settings. Use an admin Personal Access Token (PAT) with the admin scope for all provider configuration operations.

​
Configure via the API

​
List providers

GET /admin/ai/providers
Authorization: Bearer <admin-pat>
Returns all configured assistant providers for the instance.

​
Add a provider

POST /admin/ai/providers
Authorization: Bearer <admin-pat>
Content-Type: application/json
​
body.name
string
required
Display name for this provider configuration.
​
body.type
string
required
Provider type identifier (e.g. openai, anthropic).
​
body.config
object
required
Provider-specific configuration object (API key, model, endpoint, etc.).

​
Update a provider

PATCH /admin/ai/providers/:id
Authorization: Bearer <admin-pat>
Content-Type: application/json
Send only the fields you want to update in the request body.

​
Test a provider

Before attaching a provider to a workflow, verify it is reachable: 
POST /admin/ai/providers/:id/test
Authorization: Bearer <admin-pat>
Returns a test result indicating whether the provider is reachable and correctly configured.

​
Delete a provider

DELETE /admin/ai/providers/:id
Authorization: Bearer <admin-pat>
Deleting a provider that is referenced by active workflow stages will block agent dispatch for those stages until a new provider is attached.

​
Configure via the CLI

# List all configured providers
oi settings admin ai-providers list

# Test a specific provider
oi settings admin ai-providers test <provider-id>
The oi settings admin command group requires a profile configured with an admin PAT. See the authentication docs for how to create one.

​
Attaching a provider to a workflow stage

Workflow stages can be marked as agent-required in the workflow definition. When a work item enters an agent-required stage, OpenIndex looks for a configured and active assistant provider to dispatch the stage to. To enable agent dispatch:
  1. Configure at least one assistant provider via the API or CLI.
  2. Test the provider to confirm it is reachable.
  3. In your workflow definition, mark the relevant stage as agent-required and reference the provider.
If no configured provider is available when a work item reaches an agent-required stage, the stage will not dispatch and the item will remain in its current status until a provider is configured.
Use POST /admin/ai/providers/:id/test in your deployment automation to verify provider connectivity before routing production workflow stages to a new provider.