# Embedding Providers

Source: https://www.hotdata.dev/docs/api-reference/embedding-providers
Site index: https://www.hotdata.dev/llms.txt

Manage embedding providers that generate vector embeddings for text columns. Providers can be service-based (e.g., OpenAI) or local. Register a provider, then reference it when creating vector indexes on text columns.

## List embedding providers

`GET /v1/embedding-providers`

List all registered embedding providers.

**Response** `200` — List of embedding providers

- `embedding_providers` `EmbeddingProviderResponse`[] — **required**
  - `config` `any` — **required**
  - `created_at` `string` — **required**
  - `has_secret` `boolean` — **required**
  - `id` `string` — **required**
  - `name` `string` — **required**
  - `provider_type` `string` — **required**
  - `source` `string` — **required**. Provider source: "system" (from config) or "user" (created via API).
  - `updated_at` `string` — **required**

```json
{
  "embedding_providers": [
    {
      "config": null,
      "created_at": "2026-01-01T00:00:00Z",
      "has_secret": true,
      "id": "string",
      "name": "string",
      "provider_type": "string",
      "source": "string",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

## Create embedding provider

`POST /v1/embedding-providers`

Register a new embedding provider that can be used to generate vector embeddings for text columns. Providers can be service-based (e.g., OpenAI) or local.

**Request body**

- `api_key` `string,null` — Inline API key. If provided, a secret is auto-created and referenced. Cannot be used together with `secret_name`.
- `config` `object` — Provider-specific configuration (model name, base URL, dimensions, etc.)
- `name` `string` — **required**
- `provider_type` `string` — **required**. Provider type: "local" or "service"
- `secret_name` `string,null` — Reference an existing stored secret by name (for service providers). A stored secret is only sent to an approved provider origin — by default OpenAI's public API. To use a different endpoint, supply the key inline with `api_key` instead, or ask your operator to approve the origin.

```json
{
  "config": {
    "base_url": "https://api.openai.com/v1",
    "dimensions": 1536,
    "model": "text-embedding-3-small"
  },
  "name": "openai-text-embedding-3-small",
  "provider_type": "service",
  "secret_name": "openai-api-key"
}
```

**Response** `201` — Embedding provider created

- `config` `any` — **required**
- `created_at` `string` — **required**
- `id` `string` — **required**
- `name` `string` — **required**
- `provider_type` `string` — **required**

```json
{
  "config": null,
  "created_at": "2026-01-01T00:00:00Z",
  "id": "string",
  "name": "string",
  "provider_type": "string"
}
```

**Errors**

| Status | Description |
| ------ | ----------- |
| `400` | Invalid request |
| `409` | Provider with this name already exists |

## Get embedding provider

`GET /v1/embedding-providers/{id}`

**Path parameters**

- `id` `string` — **required**. Embedding provider ID

**Response** `200` — Embedding provider details

- `config` `any` — **required**
- `created_at` `string` — **required**
- `has_secret` `boolean` — **required**
- `id` `string` — **required**
- `name` `string` — **required**
- `provider_type` `string` — **required**
- `source` `string` — **required**. Provider source: "system" (from config) or "user" (created via API).
- `updated_at` `string` — **required**

```json
{
  "config": null,
  "created_at": "2026-01-01T00:00:00Z",
  "has_secret": true,
  "id": "string",
  "name": "string",
  "provider_type": "string",
  "source": "string",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

**Errors**

| Status | Description |
| ------ | ----------- |
| `404` | Provider not found |

## Update embedding provider

`PUT /v1/embedding-providers/{id}`

**Path parameters**

- `id` `string` — **required**. Embedding provider ID

**Request body**

- `api_key` `string,null` — Inline API key. If provided, updates (or creates) the auto-managed secret.
- `config` `any`
- `name` `string,null`
- `secret_name` `string,null` — Secret name containing the API key. Pass null to clear.

All fields are optional. Send only the ones you want to set.

**Response** `200` — Embedding provider updated

- `id` `string` — **required**
- `name` `string` — **required**
- `updated_at` `string` — **required**

```json
{
  "id": "string",
  "name": "string",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

**Errors**

| Status | Description |
| ------ | ----------- |
| `404` | Provider not found |

## Delete embedding provider

`DELETE /v1/embedding-providers/{id}`

**Path parameters**

- `id` `string` — **required**. Embedding provider ID

**Response** `204` — Embedding provider deleted

**Errors**

| Status | Description |
| ------ | ----------- |
| `404` | Provider not found |