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

# Embed and rerank

> Use Conare's models with the vector database you already have.

Conare's embedding and rerank models also work without namespaces, through OpenAI- and
Cohere-compatible endpoints. Point your existing client at Conare.

A service that only embeds and reranks can use a **Models only** [key](/console#keys), which
reaches no namespace.

## Embed

`POST /v1/embeddings`

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.conare.ai/v1/embeddings \
    -H "Authorization: Bearer $CONARE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "e5-mine",
      "input": ["Refunds are available for 30 days."]
    }'
  ```

  ```ts TypeScript theme={null}
  import OpenAI from "openai"; // npm install openai

  const client = new OpenAI({
    baseURL: "https://api.conare.ai/v1",
    apiKey: process.env.CONARE_API_KEY,
  });

  const docs = await client.embeddings.create({
    model: "e5-mine",
    input: ["Refunds are available for 30 days."],
  });
  const query = await client.embeddings.create({
    model: "e5-mine-query",
    input: "how do refunds work?",
  });
  ```

  ```python Python theme={null}
  import os
  from openai import OpenAI  # pip install openai

  client = OpenAI(
      base_url="https://api.conare.ai/v1",
      api_key=os.environ["CONARE_API_KEY"],
  )

  docs = client.embeddings.create(
      model="e5-mine",
      input=["Refunds are available for 30 days."],
  )
  query = client.embeddings.create(
      model="e5-mine-query",
      input="how do refunds work?",
  )
  ```
</CodeGroup>

```json Response theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0129, 0.0584, 0.0144]
    }
  ],
  "model": "e5-mine",
  "usage": { "prompt_tokens": 11, "total_tokens": 11 }
}
```

### Request

* `input` (string or array, required): 1-128 texts.
* `model` (string, default `e5-mine`): `e5-mine` for text you store, `e5-mine-query` for searches.
* `encoding_format` (string, default `float`): `float` or `base64`.

### Response

* `data`: One embedding per input, in order. Each has 1,024 numbers (shortened above).
* `usage`: The tokens read.

<Note>
  Only the first 6,000 characters of each text are embedded. A query's vector includes today's date,
  so it changes from day to day. LangChain's `OpenAIEmbeddings` needs
  `check_embedding_ctx_length=False`, or it sends token ids instead of text.
</Note>

## Rerank

`POST /v1/rerank`

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.conare.ai/v1/rerank \
    -H "Authorization: Bearer $CONARE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "how do refunds work?",
      "documents": [
        "Orders ship within two days.",
        "Refunds are available for 30 days."
      ],
      "top_n": 1
    }'
  ```

  ```ts TypeScript theme={null}
  const response = await fetch("https://api.conare.ai/v1/rerank", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CONARE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "how do refunds work?",
      documents: [
        "Orders ship within two days.",
        "Refunds are available for 30 days.",
      ],
      top_n: 1,
    }),
  });
  ```

  ```python Python theme={null}
  import os
  import cohere  # pip install cohere

  co = cohere.Client(
      base_url="https://api.conare.ai",
      api_key=os.environ["CONARE_API_KEY"],
  )

  response = co.rerank(
      query="how do refunds work?",
      documents=[
          "Orders ship within two days.",
          "Refunds are available for 30 days.",
      ],
      top_n=1,
  )
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "81bd9721-2c65-43b9-97cc-dd3141baf768",
  "model": "conare-rerank-gen2-...",
  "results": [{ "index": 1, "relevance_score": 0.38 }],
  "unscored": [],
  "usage": { "total_tokens": 57 }
}
```

### Request

* `query` (string, required): Up to 8,192 characters.
* `documents` (array, required): 1-100 documents, as strings or `{ "text": ... }` objects. Each is
  up to 24,000 characters, and together with the query up to 256,000.
* `top_n` (integer, default all): Return only the best `top_n`.
* `return_documents` (boolean, default `false`): Add each document's text to its result.

### Response

* `results`: Best first. `index` is the document's position in `documents`, and
  `relevance_score` is higher for a better match.
* `unscored`: Documents the reranker didn't reach in time. They aren't in `results`.
* `usage`: The tokens read.

Use Cohere's v1 client, `cohere.Client`. `cohere.ClientV2` calls `/v2/rerank`, which Conare doesn't
serve.

## Models

`GET /v1/models` lists the models your key can call.

| Model | Use |
| - | - |
| `e5-mine` | Embed text you store |
| `e5-mine-query` | Embed searches |
| `conare-rerank-...` | Rerank. Leave `model` out to use it. |

Models trained for your organization are listed too.

## With the Conare SDK

```ts theme={null}
const [vector] = await conare.embed("how do refunds work?", {
  type: "query",
});

const ranked = await conare.rerank("how do refunds work?", [
  "Orders ship within two days.",
  "Refunds are available for 30 days.",
]);
// [{ index: 1, score: 0.38, document: "Refunds are..." }, ...]
```

These have the same limits as the `/v1` routes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.