HTTP API¶

The HTTP API is defined using the OpenAPI schema in openapi.json.

We also host interactive swagger docs where you can try sending example queries to the HTTP API.

Generation¶

POST /chat¶

Chat

Chat API.

conversation_history: List of dicts, history of the conversation, both human and model.
model_name: String, name of the model.
request_output_len: Integer, number of tokens to generate.
temperature: Float, sampling temperature, higher is more random.
random_seed: Int, random seed, change to generate different output.
runtime_top_k: Int, only sample from the top k tokens.
runtime_top_p: Float, only sample from top tokens that sum to top_p probability.
frequency_penalty: Float, higher penalizes repetition more. 0.0 means no penalty.
presence_penalty: Float, higher penalizes repetition more. 0.0 means no penalty.
length_penalty: Float, encourage the model to be concise. 1.0 means no penalty.
stop_words: List of strings, stop generating when one is sampled.
retrieval_dataset: Optional string, the dataset name to retrieve from.
use_search_engine: Optional, boolean, whether to use a search engine.,

example:

POST /chat HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "conversation_history": [
        {
            "text": "Hello, what is your name?",
            "type": "human"
        },
        {
            "text": "Hi, I am Reka's assistant.",
            "type": "model"
        },
        {
            "text": "What is the capital of the UK?",
            "type": "human"
        }
    ],
    "frequency_penalty": 1.0,
    "length_penalty": 1.0,
    "model_name": "reka-flash",
    "presence_penalty": 1.0,
    "random_seed": 42,
    "request_output_len": 2048,
    "runtime_top_k": 1024,
    "runtime_top_p": 0.95,
    "stop_words": [],
    "temperature": 0.9,
    "use_search_engine": false
}

Status Codes:

200 OK –

Newest response from the model.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "type": "model",
    "text": "string",
    "finish_reason": "stop",
    "retrieved_chunks": [
        {
            "text": "string",
            "sourceDocument": "string",
            "sourceDocumentIsUrl": true,
            "sectionTitle": "string",
            "chunkIndex": 1,
            "isNegative": true,
            "score": 1.0
        }
    ],
    "metadata": {
        "input_tokens": 1,
        "generated_tokens": 1,
        "image_count": 1,
        "video_count": 1,
        "audio_count": 1
    }
}

Datasets¶

GET /datasets¶

List Datasets

List existing datasets.

Example request:

GET /datasets HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "string"
]

POST /datasets¶

Add Dataset

Add a new dataset from the uploaded file.

This takes form data:

file: the file to upload. Either a zip of text files or a single text file.
dataset_name: the name for the dataset.
dataset_description: optional, a description of the dataset.

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "ok": true,
    "info": "string"
}

DELETE /datasets/{dataset_name}¶

Delete Dataset

Endpoint for deleting a dataset.

To delete a job and the corresponding artifacts the following actions need to be taken in that order:

cancel any (k8s) jobs – for now we only cancel k8s jobs and not on-prem ones. Reason is that to cancel the latter, we need to keep track of pid in the job table so the Job model will diverge on_prem and on_cloud which requires a further discussion
delete weaviate artifacts and retrieval parameters
delete dataset
delete job entry

Parameters:

dataset_name (string) – The name of the dataset to delete.

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "ok": true,
    "info": "string"
}

GET /datasets/{dataset_name}¶

Get Dataset

Get information about a dataset.

Parameters:

dataset_name (string) – The name of the dataset to get details of.

Example request:

GET /datasets/{dataset_name} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "is_retrieval_prepared": true
}

Medias¶

POST /upload-media¶

Upload Image

Upload an image, providing a URL that can be used by the VLM.

This takes form data:

image - an image file.

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "image_url": "string",
    "media_url": "string"
}

Images¶

POST /upload-image¶

Upload Image

Upload an image, providing a URL that can be used by the VLM.

This takes form data:

image - an image file.

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "image_url": "string",
    "media_url": "string"
}

Files¶

POST /upload-file¶

Upload File

Upload a file, providing a URL that can be used by the code interpreter.

This takes form data:

file - an file.

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "file_url": "string"
}

Retrieval¶

POST /datasets/{dataset_name}/prepare-retrieval¶

Prepare Retrieval

Start preparing a retrieval DB for the given dataset.

Returns a job ID. You can use GET /jobs/prepare-retrieval/{job_id}/status to query the status of the job.

Parameters:

dataset_name (string) – The name of the dataset to prepare retrieval for.

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

string

GET /jobs/prepare-retrieval/{job_id}/status¶

Get Prepare Job Status

Check the status of a prepare retrieval job.

Parameters:

job_id (string) – The ID of the prepare-retrieval job to get status for.

Example request:

GET /jobs/prepare-retrieval/{job_id}/status HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Successful Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "job_status": "PENDING",
    "detail": "string",
    "history": [
        {}
    ]
}