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

# Introduction

> This document provides an overview of the OpenAI API compatible endpoints provided by amberSearch.

We have implemented the following endpoints to be compatible with the OpenAI API, allowing you to use amberSearch as a drop-in replacement for OpenAI's API. This means you can use amberSearch in applications that are designed to work with OpenAI's API without any modifications. Upon successful integration, you will also be able to use our custom tools, such as `amberSearch` and `webSearch`, to enhance your application's capabilities.

The base URL for the API is:

```
https://customerDomain.ambersearch.de/api/beta/amberai
```

Let's start with the endpoints that we support, the authentication method, and how to use the chat completion endpoint with our tools and agents.

## Supported Endpoints

* GET /models
* GET /models/{model}
* POST /chat/completions

Other endpoints that are not listed here are not supported at the moment. We've also added the rest of the endpoints regarding the models and chat completions, but they are not functional and will return an error if you try to use them.

## Authentication

Authorization for the endpoints is the same as other Endpoints. You need to provide an API key in the `Authorization` header of your request. The API key should be prefixed with `Bearer `.

```bash theme={null}
curl "https://customerDomain.ambersearch.de/api/beta/amberai/models" \
  -H "Authorization: Bearer ambrs-exampletoken"
```

## Models

Model endpoints are for getting the model identifiers, which are needed to create chat completions. Each model has a unique identifier, and you can retrieve the list of available models or details about a specific model using the following endpoints:

* `GET /models` to list all available models.
* `GET /models/{model}` to get details about a specific model.

## Chat Completions

The chat completions endpoint is used to generate responses based on a given set of messages. For getting chat completions, you can specify the model you want to use, the messages that form the conversation, and various parameters to control the generation process. It mirrors the same flow that would happen if similar inputs (messages, tools, model) were provided via the amber frontend.

Let's take a look at the endpoints:

### Create Chat Completion

The endpoint for creating chat completions is:

```
POST /chat/completions
```

We only support the following parameters in the request body:

* messages: `list`
* model: `str`
* stream: `bool`
* temperature: `float`
* metadata: `dict`
* tools: `list`

### Messages

We follow the same structure as OpenAI for the messages parameter, which is a list of message objects. Each message object should have a `role` and `content`. The roles can be one of the following:

* `system`
* `user`
* `assistant`

## Tools

We have two tools supported at the moment: `amberSearch` and `webSearch`. If no tool is passed, the model cannot perform any search in external or internal data sources. It can still e.g. give an answer based on its own knowledge only, or process an uploaded file (if it is passed as described below).

To specify which tool should be used, simply pass it in the request body as follows:

```json theme={null}
{
    "tools": [
        {
            "function": {
                "name": "webSearch"
            }
        }
    ]
}
```

The model can still decide to not use the tool if not needed for the given request.

## Agents

To create chat completions with an agent, you need to specify the agent ID in the metadata of the request body as follows:

```json theme={null}
{
    "metadata": {
        "agent_id": "9676b2b0-9fdd-40b1-8a0a-0debe64b29ac"
    }
}
```

## Files

To attach files to the chat completion request, you can use the `files` parameter in the metadata of the request body as follows:

```json theme={null}
{
    "metadata": {
        "files": ["01234567-89ab-cdef-0123-456789abcdef"]
    }
}
```

The value of the `files` parameter should be a list of file IDs that you have previously received when uploading files to amberSearch via the `/api/beta/files/upload` endpoint.

## Web search mode

When the `webSearch` tool is enabled, you can control which search engine it uses for this request via the `web_search_mode` parameter in the metadata of the request body as follows:

```json theme={null}
{
    "metadata": {
        "web_search_mode": "perplexity"
    }
}
```

The `web_search_mode` parameter accepts one of the following values:

* `search` - a standard Brave web search that also crawls the resulting pages for their full content.
* `context` - Brave's LLM Context API, which returns content optimized for grounding an LLM response without crawling individual pages.
* `perplexity` - the Perplexity Search API.

If `web_search_mode` is omitted (or set to an empty string), the tenant's configured default is used, falling back to `search` if no default is set. This parameter has no effect if the `webSearch` tool is not included in `tools`.

## Language

To specify which language your messages are in, you can use the `language` parameter in the metadata of the request body as follows:

```json theme={null}
{
    "metadata": {
        "language": "en"
    }
}
```

The default value for the `language` parameter is `de` (German). If you don't specify it, the system will assume that the messages are in German. If you want to use English, you need to explicitly set the `language` parameter to `en`.
This is mostly relevant for very short user inputs, where the model has to 'guess' the language it should respond in.