---
title: Embeddings
description: "API endpoints for embedding generation and management"
---

# Embeddings Endpoints

Endpoints for generating and managing vector embeddings for memory search.

## How Embeddings Work

Kernle converts text memories into vector embeddings for semantic search:

1. When you create a memory, its text content is embedded
2. Embeddings are stored alongside the memory
3. Search queries are embedded and compared via cosine similarity

<Info>
Embeddings are generated automatically when you create memories. These endpoints are for advanced use cases.
</Info>

---

## Generate Embedding

Generate an embedding vector for arbitrary text.

```http
POST /embeddings
```

### Headers

```
Authorization: Bearer knl_sk_your-api-key
Content-Type: application/json
```

### Request Body

```json
{
  "text": "How to debug production API issues effectively",
  "model": "default"
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `text` | string | Required | Text to embed |
| `model` | string | "default" | Embedding model to use |

### Response

```json
{
  "success": true,
  "data": {
    "embedding": [0.023, -0.156, 0.089, ...],
    "dimensions": 1536,
    "model": "text-embedding-3-small",
    "tokens_used": 12
  }
}
```

---

## Batch Generate Embeddings

Generate embeddings for multiple texts in one request.

```http
POST /embeddings/batch
```

### Headers

```
Authorization: Bearer knl_sk_your-api-key
Content-Type: application/json
```

### Request Body

```json
{
  "texts": [
    "First piece of text to embed",
    "Second piece of text to embed",
    "Third piece of text to embed"
  ],
  "model": "default"
}
```

### Response

```json
{
  "success": true,
  "data": {
    "embeddings": [
      [0.023, -0.156, ...],
      [0.089, 0.234, ...],
      [-0.045, 0.167, ...]
    ],
    "dimensions": 1536,
    "model": "text-embedding-3-small",
    "total_tokens_used": 36
  }
}
```

---

## Embedding Models

| Model | Dimensions | Quality | Speed | Cost |
|-------|------------|---------|-------|------|
| `text-embedding-3-small` | 1536 | Good | Fast | Low |
| `text-embedding-3-large` | 3072 | Best | Medium | Medium |
| `text-embedding-ada-002` | 1536 | Good | Fast | Low |

Default model: `text-embedding-3-small`

---

## Searching with Embeddings

<Tip>
For most use cases, use the `/memories/search` endpoint instead — it handles embedding generation automatically and performs semantic search in one request.
</Tip>

---

## Admin: Bulk Re-embed

Administrators can trigger bulk re-embedding for all memories. This is available via the admin API:

```http
POST /admin/embeddings/backfill
```

<Note>
This endpoint requires admin authentication. Contact support for access.
</Note>

---

## Local Embeddings

For local-only usage without the cloud API, Kernle can generate embeddings locally using:

- **sqlite-vec**: Fast local vector search
- **Sentence Transformers**: Local embedding models (optional)

Configure local embeddings in `~/.kernle/config.json`:

```json
{
  "embeddings": {
    "provider": "local",
    "model": "all-MiniLM-L6-v2"
  }
}
```
