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": [
        {}
    ]
}