> ## Documentation Index
> Fetch the complete documentation index at: https://docs.case.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddings

> Convert text into numerical vectors for semantic search, similarity comparison, and clustering

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /llm/v1/embeddings
```

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/llm/v1/embeddings \
    -H "Authorization: Bearer sk_case_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/text-embedding-3-small",
      "input": "Plaintiff alleges negligence in post-operative care"
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev llm:v1 create-embedding \
    --model openai/text-embedding-3-small \
    --input "Plaintiff alleges negligence in post-operative care"
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  import Casedev from 'casedev';

  const client = new Casedev({ apiKey: 'sk_case_YOUR_API_KEY' });

  const result = await client.llm.v1.createEmbedding({
    model: 'openai/text-embedding-3-small',
    input: 'Plaintiff alleges negligence in post-operative care'
  });

  console.log(result.data[0].embedding);  // [0.016, -0.022, ...]
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  import casedev

  client = casedev.Casedev(api_key='sk_case_YOUR_API_KEY')

  result = client.llm.v1.create_embedding(
      model='openai/text-embedding-3-small',
      input='Plaintiff alleges negligence in post-operative care'
  )

  print(result.data[0].embedding)  # [0.016, -0.022, ...]
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result, _ := client.Llm.V1.NewEmbedding(ctx, casedev.LlmV1NewEmbeddingParams{
  	Model: casedev.F("openai/text-embedding-3-small"),
  	Input: casedev.F("Plaintiff alleges negligence in post-operative care"),
  })
  fmt.Println(result.Data[0].Embedding)
  ```
</CodeGroup>

```json title="Response" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.016, 0.022, -0.011, ...]
    }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}
```

## Parameters

| Parameter | Type            | Required | Description        |
| --------- | --------------- | -------- | ------------------ |
| `model`   | string          | **Yes**  | Embedding model ID |
| `input`   | string or array | **Yes**  | Text(s) to embed   |

## Embedding models

| Model                           | Dimensions | Best for            | \$/1K tokens |
| ------------------------------- | ---------- | ------------------- | ------------ |
| `openai/text-embedding-3-small` | 1536       | General purpose     | \$0.00002    |
| `openai/text-embedding-3-large` | 3072       | Higher quality      | \$0.00013    |
| `voyage/voyage-law-2`           | 1024       | **Legal documents** | \$0.00012    |
| `voyage/voyage-3.5`             | 1536       | General purpose     | \$0.00006    |

<Info>
  **For legal documents,** use `voyage/voyage-law-2`. It's specifically trained on legal text.
</Info>

## Batch embeddings

Embed multiple texts in one request:

<CodeGroup>
  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev llm:v1 create-embedding \
    --model openai/text-embedding-3-small \
    --input "Plaintiff alleges negligence in post-operative care"
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const result = await client.llm.v1.createEmbedding({
    model: 'openai/text-embedding-3-small',
    input: [
      'Medical record from January 2024',
      'Deposition transcript page 45',
      'Expert witness report summary'
    ]
  });

  // result.data[0].embedding, result.data[1].embedding, ...
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result = client.llm.v1.create_embedding(
      model='openai/text-embedding-3-small',
      input=[
          'Medical record from January 2024',
          'Deposition transcript page 45',
          'Expert witness report summary'
      ]
  )

  # result.data[0].embedding, result.data[1].embedding, ...
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result, _ := client.Llm.V1.NewEmbedding(ctx, casedev.LlmV1NewEmbeddingParams{
  	Model: casedev.F("openai/text-embedding-3-small"),
  	Input: casedev.F([]string{
  		"Text one",
  		"Text two",
  		"Text three",
  	}),
  })
  // result.Data[0].Embedding, result.Data[1].Embedding, ...
  ```
</CodeGroup>

## Use cases

### Semantic search

<CodeGroup>
  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # 1. Embed your query
  casedev llm:v1 create-embedding \
    --model voyage/voyage-law-2 \
    --input "negligence in surgical procedure"

  # 2. Compare to document embeddings (cosine similarity)
  # 3. Return most similar documents
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // 1. Embed your query
  const queryResult = await client.llm.v1.createEmbedding({
    model: 'voyage/voyage-law-2',
    input: 'negligence in surgical procedure'
  });

  // 2. Compare to document embeddings (cosine similarity)
  // 3. Return most similar documents
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # 1. Embed your query
  query_result = client.llm.v1.create_embedding(
      model='voyage/voyage-law-2',
      input='negligence in surgical procedure'
  )

  # 2. Compare to document embeddings (cosine similarity)
  # 3. Return most similar documents
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // 1. Embed your query
  queryResult, _ := client.Llm.V1.NewEmbedding(ctx, casedev.LlmV1NewEmbeddingParams{
  	Model: casedev.F("voyage/voyage-law-2"),
  	Input: casedev.F("negligence in surgical procedure"),
  })

  // 2. Compare to document embeddings (cosine similarity)
  // 3. Return most similar documents
  ```
</CodeGroup>

### Document similarity

<CodeGroup>
  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # Compare two documents (embed each separately, then compute similarity)
  casedev llm:v1 create-embedding \
    --model voyage/voyage-law-2 \
    --input "Plaintiff expert testimony on standard of care"

  casedev llm:v1 create-embedding \
    --model voyage/voyage-law-2 \
    --input "Defense expert rebuttal on treatment protocols"
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // Compare two documents
  const result = await client.llm.v1.createEmbedding({
    model: 'voyage/voyage-law-2',
    input: [
      'Plaintiff expert testimony on standard of care',
      'Defense expert rebuttal on treatment protocols'
    ]
  });

  // Calculate cosine similarity:
  // ~1.0 = very similar, ~0.5 = somewhat related, ~0.0 = unrelated
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  # Compare two documents
  result = client.llm.v1.create_embedding(
      model='voyage/voyage-law-2',
      input=[
          'Plaintiff expert testimony on standard of care',
          'Defense expert rebuttal on treatment protocols'
      ]
  )

  # Calculate cosine similarity:
  # ~1.0 = very similar, ~0.5 = somewhat related, ~0.0 = unrelated
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // Compare two documents
  result, _ := client.Llm.V1.NewEmbedding(ctx, casedev.LlmV1NewEmbeddingParams{
  	Model: casedev.F("voyage/voyage-law-2"),
  	Input: casedev.F([]string{
  		"Plaintiff expert testimony on standard of care",
  		"Defense expert rebuttal on treatment protocols",
  	}),
  })

  // Calculate cosine similarity:
  // ~1.0 = very similar, ~0.5 = somewhat related, ~0.0 = unrelated
  ```
</CodeGroup>

<Info>
  **Tip:** Use the same model for indexing and querying. Mixing models produces poor results.
</Info>