Providers

Endpoints for managing AI service provider credentials and configurations.

GET /api/providers

List all AI providers configured for the tenant.

Authentication: permission.ai.manage

Response:

{
  "_links": {
    "self": { "href": "/api/providers" }
  },
  "_embedded": {
    "inf:provider": [
      {
        "id": "anthropic-123",
        "name": "Anthropic",
        "type": "anthropic",
        "managed": true,
        "internal": false,
        "credential": {
          "type": "enterprise",
          "configured": true
        },
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "openai-456",
        "name": "OpenAI",
        "type": "openai",
        "managed": false,
        "internal": false,
        "credential": {
          "type": "api_key",
          "configured": true
        },
        "createdAt": "2024-01-10T12:00:00Z",
        "updatedAt": "2024-01-10T12:00:00Z"
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

Provider Properties:

Field	Type	Description
id	string	Unique provider ID
name	string	Display name
type	string	Provider type (e.g., anthropic, openai, google)
managed	boolean	System-managed provider
internal	boolean	Internal-only provider
credential	object	Credential configuration (sensitive data redacted)
createdAt	date	Creation timestamp
updatedAt	date	Last update timestamp

---

POST /api/providers

Create a new AI provider with credentials.

Authentication: permission.ai.manage

Pre-blocks: permission.ai.manage

Request Body:

Field	Type	Required	Description
name	string	Yes	Provider display name
type	string	Yes	Provider type (see types endpoint)
credential	object	Yes	Provider credentials (enterprise credential required)

Example Request:

{
  "name": "Custom OpenAI",
  "type": "openai",
  "credential": {
    "type": "api_key",
    "apiKey": "sk-..."
  }
}

Response:

{
  "id": "custom-789",
  "name": "Custom OpenAI",
  "type": "openai",
  "managed": false,
  "internal": false,
  "credential": {
    "type": "api_key",
    "configured": true
  },
  "createdAt": "2024-01-15T14:00:00Z"
}

Enterprise Credentials Required

Creating providers requires enterprise-level credentials. Contact your administrator to configure provider access.

---

GET /api/providers/{id}

Retrieve a specific provider's configuration.

Authentication: permission.ai.manage

Pre-blocks:

• provider.lookup
• permission.ai.manage

Response:

Provider object with full details (credentials redacted).

---

PUT /api/providers/{id}

Update a provider's configuration.

Authentication: permission.ai.manage

Pre-blocks:

• provider.lookup
• permission.ai.manage

Request Body:

Field	Type	Description
name	string	Update display name
credential	object	Update credentials

Managed Provider Restrictions:

• Internal and managed providers have limited update capabilities
• Can update credentials (key rotation)
• Cannot change provider type
• Cannot delete

Example Request:

{
  "credential": {
    "type": "api_key",
    "apiKey": "sk-new-key..."
  }
}

Response:

Returns the updated provider object.

---

DELETE /api/providers/{id}

Delete a provider and all associated models.

Authentication: permission.ai.manage

Pre-blocks:

• provider.lookup
• permission.ai.manage

Response:

204 No Content

Restrictions:

• Cannot delete managed providers
• Cannot delete providers with models in active use
• Cascades to delete all provider models

Cascade Deletion

Deleting a provider removes all associated models. Ensure models are not referenced by active chats before deletion.

---

GET /api/provider-types

Discover available provider types supported by the system.

Authentication: permission.ai.manage

Response:

{
  "types": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "description": "Anthropic's Claude models",
      "credentialTypes": ["api_key", "enterprise"],
      "capabilities": ["chat", "attachments", "web"],
      "documentationUrl": "https://docs.anthropic.com"
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "description": "OpenAI's GPT models",
      "credentialTypes": ["api_key"],
      "capabilities": ["chat", "generateImage", "createEmbeddings"],
      "documentationUrl": "https://platform.openai.com/docs"
    }
  ]
}

Type Properties:

Field	Type	Description
id	string	Provider type identifier
name	string	Display name
description	string	Provider description
credentialTypes	array	Supported credential types
capabilities	array	Available model capabilities
documentationUrl	string	Provider documentation link

Use Cases:

• Discover available providers before creating
• Validate credential types
• Display provider selection UI

---

GET /api/providers/{id}/models

List all models available from a provider.

Authentication: permission.ai.manage

Pre-blocks:

• provider.lookup
• permission.ai.manage

Response:

{
  "_links": {
    "self": { "href": "/api/providers/{id}/models" }
  },
  "_embedded": {
    "inf:model": [
      {
        "id": "claude-opus-4",
        "name": "Claude Opus 4",
        "providerId": "anthropic-123",
        "model": "claude-opus-4-20250514",
        "chat": true,
        "tier": "strategic"
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

---

POST /api/providers/{id}/models

Create a new model for a specific provider.

Authentication: permission.ai.manage

Pre-blocks:

• provider.lookup
• permission.ai.manage

Request Body:

Same as POST /api/models but providerId is automatically set from the URL.

Example Request:

{
  "model": "gpt-4-turbo",
  "name": "GPT-4 Turbo",
  "slug": "gpt-4-turbo",
  "chat": true,
  "tier": "advanced",
  "promptPpm": 10.0,
  "completionPpm": 30.0
}

Response:

Returns the created model object.

Provider Discovery

Use the provider types endpoint to discover available providers before creating custom provider configurations.