Skip to main content
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/
  • 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 . 
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: 
{
    "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: 
{
    "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: 
{
    "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.

​
Language

To specify which language your messages are in, you can use the language parameter in the metadata of the request body as follows: 
{
    "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.