Custom Providers

Last updated Jun 15, 2026

Overview

Custom Providers allow you to integrate AI providers that are not natively supported by AI Gateway. This feature enables you to use AI Gateway's observability, caching, rate limiting, and other features with any AI provider that has an HTTPS API endpoint.

Use cases

  • Internal AI models: Connect to your organization's self-hosted AI models
  • Regional providers: Integrate with AI providers specific to your region
  • Specialized models: Use domain-specific AI services not available through standard providers
  • Custom endpoints: Route requests to your own AI infrastructure

Before you begin

Prerequisites

  • An active Cloudflare account with AI Gateway access
  • A valid API key from your custom AI provider
  • The HTTPS base URL for your provider's API

Authentication

The API endpoints for creating, reading, updating, or deleting custom providers require authentication. You need to create a Cloudflare API token with the appropriate permissions.

To create an API token:

  1. Go to the Cloudflare dashboard API tokens page ↗︎
  2. Click Create Token
  3. Select Custom Token and add the following permissions:
  4. AI Gateway - Edit
  5. Click Continue to summary and then Create Token
  6. Copy the token - you'll use it in the Authorization: Bearer $CLOUDFLARE_API_TOKEN header

Create a custom provider

To create a new custom provider using the API:

  1. Get your Account ID and Account Tag.
  2. Send a POST request to create a new custom provider:

Create Custom Providerbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true
  }'

Required fields:

  • name (string): Display name for your provider
  • slug (string): Unique identifier (alphanumeric with hyphens). Must be unique within your account.
  • base_url (string): HTTPS URL for your provider's API endpoint. Must start with https://.

Optional fields:

  • description (string): Description of the provider
  • link (string): URL to provider documentation
  • enable (boolean): Whether the provider is active (default: false)
  • beta (boolean): Mark as beta feature (default: false)
  • curl_example (string): Example cURL command for using the provider
  • js_example (string): Example JavaScript code for using the provider

Response:

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "abc123def456",
    "account_tag": "my-account",
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true,
    "beta": false,
    "logo": "Base64 encoded SVG logo",
    "link": null,
    "curl_example": null,
    "js_example": null,
    "created_at": 1700000000,
    "modified_at": 1700000000
  }
}

Auto-generated logo

A default SVG logo is automatically generated for each custom provider. The logo is returned as a base64-encoded string.

To create a new custom provider using the dashboard:

  1. Log in to the Cloudflare dashboard ↗︎ and select your account.
  2. Go to Compute & AI > AI Gateway > Custom Providers ↗︎.
  3. Select Add Custom Provider.
  4. Enter the following information:
  5. Provider Name: Display name for your provider
  6. Provider Slug: Unique identifier (alphanumeric with hyphens)
  7. Base URL: HTTPS URL for your provider's API endpoint (e.g., https://api.myprovider.com/v1)
  8. Select Save to create your custom provider.

List custom providers

Retrieve all custom providers with optional filtering and pagination:

List all providersbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Query parameters:

  • page (number): Page number (default: 1)
  • per_page (number): Items per page (default: 20, max: 100)
  • enable (boolean): Filter by enabled status
  • beta (boolean): Filter by beta status
  • search (string): Search in id, name, or slug fields
  • order_by (string): Sort field and direction (default: "name ASC")

Examples:

List only enabled providers:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers?enable=true" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Search for specific providers:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers?search=custom" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Response:

{
  "success": true,
  "result": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Custom Provider",
      "slug": "some-provider",
      "base_url": "https://api.myprovider.com",
      "enable": true,
      "created_at": 1700000000,
      "modified_at": 1700000000
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "total_count": 1,
    "total_pages": 1
  }
}

To view all your custom providers:

  1. Log in to the Cloudflare dashboard ↗︎ and select your account.
  2. Go to Compute & AI > AI Gateway > Custom Providers ↗︎.
  3. You will see a list of all your custom providers with their names, slugs, base URLs, and status.

Get a specific custom provider

Retrieve details for a specific custom provider by its ID:

Get provider by IDbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Response:

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "abc123def456",
    "account_tag": "my-account",
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true,
    "beta": false,
    "logo": "Base64 encoded SVG logo",
    "link": "https://docs.myprovider.com",
    "curl_example": "curl -X POST https://api.myprovider.com/v1/chat ...",
    "js_example": "fetch('https://api.myprovider.com/v1/chat', {...})",
    "created_at": 1700000000,
    "modified_at": 1700000000
  }
}

Update a custom provider

Update an existing custom provider. All fields are optional - only include the fields you want to change:

Update providerbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Provider Name",
    "enable": true,
    "description": "Updated description"
  }'

Updatable fields:

  • name (string): Provider display name
  • slug (string): Provider identifier
  • base_url (string): API endpoint URL (must be HTTPS)
  • description (string): Provider description
  • link (string): Documentation URL
  • enable (boolean): Active status
  • beta (boolean): Beta flag
  • curl_example (string): Example cURL command
  • js_example (string): Example JavaScript code

Examples:

Enable a provider:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enable": true}'

Update provider URL:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_url": "https://api.newprovider.com"}'

Cache invalidation

Updates to custom providers automatically invalidate any cached entries related to that provider.

To update an existing custom provider:

  1. Log in to the Cloudflare dashboard ↗︎ and select your account.
  2. Go to Compute & AI > AI Gateway > Custom Providers ↗︎.
  3. Find the custom provider you want to update and select Edit.
  4. Update the fields you want to change (name, slug, base URL, etc.).
  5. Select Save to apply your changes.

Delete a custom provider

Delete a custom provider:

Delete providerbash

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Response:

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Custom Provider",
    "slug": "some-provider"
  }
}

Impact of deletion

Deleting a custom provider will immediately stop all requests routed through it. Ensure you have updated your applications before deleting a provider. Cache entries related to the provider will also be invalidated.

To delete a custom provider:

  1. Log in to the Cloudflare dashboard ↗︎ and select your account.
  2. Go to Compute & AI > AI Gateway > Custom Providers ↗︎.
  3. Find the custom provider you want to delete and select Delete.
  4. Confirm the deletion when prompted.

Impact of deletion

Deleting a custom provider will immediately stop all requests routed through it. Ensure you have updated your applications before deleting a provider.

Using custom providers with AI Gateway

Once you've created a custom provider, you can route requests through AI Gateway using one of two approaches: the Unified API or the provider-specific endpoint. When referencing your custom provider with either approach, you must prefix the slug with custom-.

Custom provider prefix

All custom provider slugs must be prefixed with custom- when making requests through AI Gateway. For example, if your provider slug is some-provider, you must use custom-some-provider in your requests.

How URL routing works

When AI Gateway receives a request for a custom provider, it constructs the upstream URL by combining the provider's configured base_url with the path that comes after custom-{slug}/ in the gateway URL.

The base_url field should contain only the root domain (or domain with a fixed prefix) of the provider's API. Any API-specific path segments (like /v1/chat/completions) go in the request URL, not in base_url.

The formula is:

Gateway URL:   https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-{slug}/{provider-path}
Upstream URL:  {base_url}/{provider-path}

Everything after custom-{slug}/ in your request URL is appended directly to the base_url to form the final upstream URL. This means {provider-path} can include multiple path segments, query parameters, or any path structure your provider requires.

Choosing between Unified API and provider-specific endpoint