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

# API reference

> REST API reference

# Overview

The Adaptive REST API provides endpoints for inference, feedback, and interactions.

Base URL: `https://your-adaptive-instance/api/v1`

***

## Chunked Upload

### `POST /api/v1/upload/init`

**Initialize Chunked Upload**

Start a new chunked upload session for large files. Returns a session ID to be used for uploading parts.

**Request Body**

<ParamField body="parameters">
  * **content\_type** (`string | null`): MIME type of the file being uploaded
  * **metadata** (`object | null`): Custom metadata to attach to the upload session
  * **total\_parts\_count** (`integer<int32>`) *(required)*: Total number of parts that will be uploaded
</ParamField>

**Response** (`InitChunkedUploadResponse`)

Upload session created successfully

### `POST /api/v1/upload/part`

**Upload Part**

Upload a single part (chunk) of a file to an existing upload session.

<ParamField body="parameters">
  * **session\_id** (`string`, query) *(required)*: Upload session identifier
  * **part\_number** (`integer<int32>`, query) *(required)*: Part number (1-indexed)
</ParamField>

### `DELETE /api/v1/upload/abort`

**Abort Chunked Upload**

Cancel an ongoing chunked upload session and clean up any uploaded parts.

**Request Body**

<ParamField body="parameters">
  * **session\_id** (`string`) *(required)*: Upload session identifier to abort
</ParamField>

### `POST /api/v1/upload/status`

**Get Upload Session Status**

Cancel an ongoing chunked upload session and clean up any uploaded parts.

**Request Body**

<ParamField body="parameters">
  * **session\_id** (`string`) *(required)*:
</ParamField>

**Response** (`GetUploadSessionStatusResponse`)

Upload session status retrieved successfully

***

## Completions

### `POST /api/v1/chat/completions`

**Generate chat completion**

Generate a chat completion from a prompt using one model in your project.
Your prompt messages can include several roles.
This endpoints supports streaming

**Request Body**

<ParamField body="parameters">
  * **stop** (`string[] | null`):
  * **max\_tokens** (`integer<int32> | null`):
  * **temperature** (`number<float> | null`):
  * **top\_p** (`number<float> | null`):
  * **max\_ttft\_ms** (`integer<int64> | null`):
  * **messages** (`ChatMessageInput[]`) *(required)*:
  * **model** (`string`) *(required)*: can be of the form `{project}/{model}` or `{project}`. In the latter it will use the default model
  * **stream** (`boolean`):
  * **stream\_options** (`any`):
  * **session\_id** (`string<uuid> | null`):
  * **user** (`string<uuid> | null`):
  * **ab\_campaign** (`any`):
  * **n** (`integer<int32>`):
  * **labels** (`any`):
  * **metadata** (`any`):
  * **system\_prompt\_args** (`object | null`): Will be used to render system prompt template
  * **tags** (`string[] | null`):
  * **use\_tools** (`boolean`):
  * **tools** (`ToolOverride[] | null`): Override tool configuration for this request - enables/disables specific tools
  * **store** (`boolean | null`):
</ParamField>

**Response** (`ChatResponse`)

a stream will be returned if `streaming = true` in the request

***

## Datasets

### `GET /api/v1/projects/{project}/datasets/{dataset_id}/download`

**Download a dataset file from storage**

Returns the dataset JSONL file as an attachment

<ParamField body="parameters">
  * **project** (`IdOrKey`, path) *(required)*: Project ID or key
  * **dataset** (`IdOrKey`, path) *(required)*: Dataset ID or key
  * **format** (`string`, query): File format: 'recipe' (converted format) or 'original' (as uploaded). Defaults to 'original'. If original file is not available, falls back to recipe format.
  * **dataset\_id** (`IdOrKey`, path) *(required)*:
</ParamField>

***

## Embeddings

### `POST /api/v1/embeddings`

**Request Body**

<ParamField body="parameters">
  * **input** (`string`) *(required)*:
  * **model** (`string`) *(required)*: can be of the form '{project}/{model}' or '{project}'. In the latter it will use the default model
  * **encoding\_format** (`any`):
  * **dimensions** (`integer<int32> | null`):
  * **user** (`string<uuid> | null`):
  * **session\_id** (`string<uuid> | null`):
</ParamField>

**Response** (`EmbeddingsResponseList`)

***

## Feedback

### `POST /api/v1/comparison`

**Add comparison**

Register a comparison between two interactions to indicate a preference according to a criteria.
Both interactions should share the same prompt.

**Request Body**

<ParamField body="parameters">
  * **metric** (`IdOrKey`) *(required)*:
  * **messages** (`ChatMessageInput[] | null`): Required when using raw text for completion, ignored if using ids
  * **preferred\_completion** (`CompletionIdOrText`) *(required)*:
  * **other\_completion** (`CompletionIdOrText`) *(required)*:
  * **tied** (`any`):
  * **project** (`IdOrKey`) *(required)*:
  * **user\_id** (`string<uuid> | null`):
</ParamField>

**Response** (`ComparisonOutput`)

Comparison recorded

### `POST /api/v1/outcome`

**Add outcome**

Register an outcome about a previous user session

**Request Body**

<ParamField body="parameters">
  * **value** (`any`) *(required)*: If the metric is Bool, accepts `0`, `1`, `true` or `false`
    If the metric is Scalar, accepts number
  * **project\_id** (`IdOrKey`) *(required)*:
  * **metric** (`IdOrKey`) *(required)*:
  * **session\_id** (`string<uuid>`) *(required)*:
  * **user\_id** (`string<uuid> | null`):
</ParamField>

**Response** (`OutcomeOutput`)

outcome recorded

***

## Interactions

### `POST /api/v1/interactions`

**Add interaction**

Import an interaction in your project. You can also include feedback about the interaction

**Request Body**

<ParamField body="parameters">
  * **model\_service** (`any`):
  * **project** (`IdOrKey`) *(required)*:
  * **messages** (`ChatMessageInput[]`) *(required)*:
  * **completion** (`string`) *(required)*:
  * **feedbacks** (`InteractionFeedback[]`):
  * **user** (`string<uuid> | null`):
  * **session\_id** (`string<uuid> | null`):
  * **created\_at** (`any`):
  * **ab\_campaign** (`any`):
  * **labels** (`any`):
</ParamField>

**Response** (`AddInteractionsResponse`)

Interaction recorded

***

## Recipes

### `GET /api/v1/projects/{project}/recipes/{recipe}/download`

**Download a recipe zip file from storage**

Returns the recipe zip file as an attachment.
Supports both project-specific recipes and global recipes (available in all projects).

<ParamField body="parameters">
  * **project** (`IdOrKey`, path) *(required)*: Project ID or key
  * **recipe** (`IdOrKey`, path) *(required)*: Recipe ID or key
</ParamField>

***

## artifacts::rest

### `GET /artifacts/{artifact_id}/download`

<ParamField body="parameters">
  * **artifact\_id** (`string<uuid>`, path) *(required)*: Unique identifier for the artifact
</ParamField>

***

## image::rest

### `GET /images/{project_id}/{filename}`

<ParamField body="parameters">
  * **project\_id** (`string<uuid>`, path) *(required)*: Project ID the image belongs to
  * **filename** (`string`, path) *(required)*: Image filename (hash.ext)
</ParamField>