> For the complete documentation index, see [llms.txt](https://docs.karini.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.karini.ai/api-documentation.md).

# API Documentation

### Overview

The Karini AI platform exposes a RESTful API for managing recipes, copilots, webhooks, dataset search, and observability traces. All API endpoints are accessible via HTTPS and return JSON responses.

***

### Authentication

All API requests require authentication via HTTP headers. The following authentication schemes are supported:

| Header       | Description                                                |
| ------------ | ---------------------------------------------------------- |
| x-api-key    | Your organization's API key for authenticating requests    |
| x-api-token  | API token for webhook and external integrations            |
| x-origin     | The origin domain of the request                           |
| x-session-id | Session ID for session-based authentication (copilot chat) |
| Content-Type | Must be application/json for all request bodies            |

Different endpoints use different authentication headers. Refer to each endpoint's documentation for specific requirements.

***

### Recipes

Recipes are configurable AI workflows that define how the system processes user queries. They support multiple types including QnA, Agent, and Graph RAG.

#### Create Recipe

Creates a new recipe with the provided configuration.

| Endpoint | POST /api/recipe/ |
| -------- | ----------------- |
| Auth     | x-api-key         |

Request Body Fields:

| Field       | Type   | Required | Description                                         |
| ----------- | ------ | -------- | --------------------------------------------------- |
| name        | string | Yes      | Recipe name (3-32 alphanumeric characters/spaces)   |
| type        | string | Yes      | Recipe type: qna, agent2, graph\_rag, or aws\_q     |
| runtime     | string | No       | Runtime environment: karini (default) or databricks |
| description | string | No       | Description of the recipe's purpose                 |

Response Fields (200):

| Field                 | Type     | Description                             |
| --------------------- | -------- | --------------------------------------- |
| status                | integer  | 1 for success                           |
| data.\_id             | string   | Unique identifier of the created recipe |
| data.name             | string   | Recipe name                             |
| data.type             | string   | Recipe type                             |
| data.runtime          | string   | Runtime environment                     |
| data.creator          | string   | ID of the user who created the recipe   |
| data.organization     | string   | Organization ID                         |
| data.current\_version | string   | ID of the current version               |
| data.created          | datetime | Creation timestamp                      |
| data.modified         | datetime | Last modification timestamp             |
| data.active           | boolean  | Whether the recipe is active            |

***

#### Publish Recipe

Publishes a recipe version by updating the recipe with the provided version configuration.

| Endpoint | PATCH /api/recipe/{id} |
| -------- | ---------------------- |
| Auth     | x-api-key              |

Path Parameters:

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| id        | string | Yes      | Unique identifier for the recipe |

Request Body Fields:

| Field               | Type    | Required | Description                         |
| ------------------- | ------- | -------- | ----------------------------------- |
| \_id                | string  | Yes      | Recipe unique identifier            |
| current\_version    | string  | Yes      | Current version ID of the recipe    |
| version.\_id        | string  | Yes      | Version ID to publish               |
| version.publish     | boolean | Yes      | Set to true to publish this version |
| version.name        | string  | No       | Version name (e.g., "v1")           |
| version.nodes       | array   | No       | Array of flow nodes                 |
| version.edges       | array   | No       | Array of connections between nodes  |
| version.extra\_data | object  | No       | Additional version metadata         |

Response Fields (200):

| Field             | Type     | Description                  |
| ----------------- | -------- | ---------------------------- |
| status            | integer  | 1 for success                |
| data.\_id         | string   | Recipe ID                    |
| data.name         | string   | Recipe name                  |
| data.type         | string   | Recipe type                  |
| data.creator      | string   | Creator user ID              |
| data.modified\_by | string   | ID of user who last modified |
| data.organization | string   | Organization ID              |
| data.created      | datetime | Creation timestamp           |
| data.modified     | datetime | Last modification timestamp  |
| data.active       | boolean  | Whether the recipe is active |

***

#### Deploy Recipe Version

Deploys a specific version of a recipe by updating the deployed\_version field.

| Endpoint | GET /api/recipe/{id}/deploy |
| -------- | --------------------------- |
| Auth     | x-api-key                   |

Path Parameters:

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| id        | string | Yes      | Unique identifier for the recipe |

Query Parameters:

| Parameter       | Type   | Required | Description              |
| --------------- | ------ | -------- | ------------------------ |
| deploy\_version | string | Yes      | Version number to deploy |

Response Fields (200):

| Field   | Type    | Description                             |
| ------- | ------- | --------------------------------------- |
| status  | integer | 1 for success                           |
| message | string  | "Successfully updated deployed version" |
| recipe  | object  | The updated recipe object               |

***

#### Get Recipe Versions

Returns all versions of a recipe, or a specific version if the version query parameter is provided.

| Endpoint | GET /api/recipe/{id}/versions |
| -------- | ----------------------------- |
| Auth     | x-api-key                     |

Path Parameters:

| Parameter | Type   | Required | Description          |
| --------- | ------ | -------- | -------------------- |
| id        | string | Yes      | The ID of the recipe |

Query Parameters:

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| version   | string | No       | Specific version ID to retrieve |

Response Fields (200):

| Field   | Type    | Description                    |
| ------- | ------- | ------------------------------ |
| success | integer | 1 for success                  |
| data    | array   | List of recipe version objects |

***

#### Export Recipe

Exports recipe data for future importing.

| Endpoint | GET /api/recipe/{id}/export |
| -------- | --------------------------- |
| Auth     | x-api-key                   |

Path Parameters:

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| id        | string | Yes      | Unique identifier for the recipe |

Response: Returns the full recipe export payload as JSON.

***

#### Import Recipe

Imports recipe configuration from a payload.

| Endpoint | POST /api/recipe/{id}/import |
| -------- | ---------------------------- |
| Auth     | x-api-key                    |

Path Parameters:

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| id        | string | Yes      | Unique identifier for the recipe |

Request Body Fields:

| Field            | Type    | Required | Description                                  |
| ---------------- | ------- | -------- | -------------------------------------------- |
| data.type        | string  | Yes      | Recipe type (e.g., qna)                      |
| data.nodes       | array   | Yes      | Array of recipe nodes                        |
| data.edges       | array   | Yes      | Array of node connections                    |
| data.extra\_data | object  | No       | Additional recipe data                       |
| clone            | boolean | No       | Whether to clone the recipe (default: false) |

***

#### Create/Update Recipe Schedule

Creates or updates a scheduled run for a recipe.

| Endpoint | POST /api/recipe/{id}/schedule |
| -------- | ------------------------------ |
| Auth     | x-api-key                      |

Path Parameters:

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| id        | string | Yes      | Unique identifier for the recipe |

Request Body Fields:

| Field                | Type              | Required    | Description                                                  |
| -------------------- | ----------------- | ----------- | ------------------------------------------------------------ |
| scheduled\_date      | string (ISO 8601) | Yes         | Date/time for the scheduled run                              |
| input\_message       | string            | Yes         | Input message for the scheduled run                          |
| recurring            | boolean           | Yes         | Whether the schedule repeats                                 |
| recurring\_frequency | integer           | Conditional | Frequency value (required if recurring: true)                |
| recurring\_period    | string            | Conditional | Period unit: days, hours, etc. (required if recurring: true) |

Response Fields (200):

| Field         | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| batch\_status | string | Status of the batch (e.g., "inProgress") |
| request\_id   | string | Unique request identifier                |
| recipe\_id    | string | Recipe identifier                        |

***

#### Get Recipe Schedule

Retrieves the schedule configuration for a recipe.

| Endpoint | GET /api/recipe/{id}/schedule |
| -------- | ----------------------------- |
| Auth     | x-api-key                     |

Path Parameters:

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| id        | string | Yes      | Unique identifier for the recipe |

***

#### Delete Recipe Schedule

Deletes the schedule for a recipe.

| Endpoint | DELETE /api/recipe/{id}/schedule |
| -------- | -------------------------------- |
| Auth     | x-api-key                        |

Path Parameters:

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| id        | string | Yes      | Unique identifier for the recipe |

***

#### Delete Recipe

Soft-deletes a recipe and all associated data (versions, copilots, batch runs, schedules, actions, evaluations).

| Endpoint | DELETE /api/recipe/{id}/delete |
| -------- | ------------------------------ |
| Auth     | x-api-key                      |

Path Parameters:

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| id        | string | Yes      | Unique identifier for the recipe to delete |

Response Fields (200):

| Field          | Type    | Description                           |
| -------------- | ------- | ------------------------------------- |
| status         | integer | 1 for success                         |
| message        | string  | Success confirmation message          |
| recipe         | object  | The deleted recipe object             |
| versions       | object  | Result of version deactivation        |
| copilots       | object  | Result of copilot deactivation        |
| batchRun       | object  | Result of batch run deactivation      |
| recipeSchedule | object  | Result of schedule deactivation       |
| actionrun      | object  | Result of action run deactivation     |
| action         | object  | Result of action deactivation         |
| evaluationrun  | object  | Result of evaluation run deactivation |
| evaluation     | object  | Result of evaluation deactivation     |

***

### Copilots

Copilots are AI-powered chat assistants built on top of recipes. They handle user conversations, maintain session state, and provide intelligent responses.

#### Chat with Copilot

Initiates a chat session with a specific copilot.

| Endpoint | POST /api/copilot/{id}           |
| -------- | -------------------------------- |
| Auth     | x-api-key, x-api-token, x-origin |

Path Parameters:

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| id        | string | Yes      | Unique identifier for the copilot |

Request Body Fields:

| Field                                      | Type    | Required | Description                                        |
| ------------------------------------------ | ------- | -------- | -------------------------------------------------- |
| question                                   | string  | Yes      | The user's question or message                     |
| suggest\_followup\_questions               | boolean | No       | Whether to generate follow-up question suggestions |
| disable\_scratchpad                        | boolean | No       | Whether to disable the agent scratchpad            |
| external\_user\_data.origin.type           | string  | No       | Origin platform type (e.g., teams, widget, slack)  |
| external\_user\_data.origin.id             | string  | No       | Origin copilot ID                                  |
| external\_user\_data.origin.name           | string  | No       | Origin copilot name                                |
| external\_user\_data.user\_Auth0\_metadata | array   | No       | User group metadata for access control             |
| external\_user\_data.external\_thread      | string  | No       | External thread ID for conversation continuity     |

***

#### Create Copilot Session

Creates a new user session for use in future copilot requests.

| Endpoint | POST /api/copilot/{id}/create\_session |
| -------- | -------------------------------------- |
| Auth     | x-api-key, x-api-token, x-origin       |

Path Parameters:

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| id        | string | Yes      | Unique identifier for the copilot |

Request Body Fields:

| Field            | Type   | Required | Description                  |
| ---------------- | ------ | -------- | ---------------------------- |
| origin.type      | string | Yes      | Platform type: widget, teams |
| origin.id        | string | Yes      | Origin copilot ID            |
| origin.name      | string | Yes      | Copilot name                 |
| user.email       | string | Yes      | User email address           |
| user.id          | string | Yes      | User origin ID               |
| user.name        | string | Yes      | User display name            |
| external\_thread | string | Yes      | Unique thread identifier     |

Response: Returns a session object containing the x-session-id to use in subsequent requests.

***

#### Update Copilot Configuration

Updates or modifies the configuration settings of a specific copilot.

| Endpoint | POST /api/copilot/{id}/config    |
| -------- | -------------------------------- |
| Auth     | x-api-key, x-api-token, x-origin |

Path Parameters:

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| id        | string | Yes      | Unique identifier for the copilot |

Request Body Fields:

| Field                                 | Type    | Required | Description                                        |
| ------------------------------------- | ------- | -------- | -------------------------------------------------- |
| external\_user\_data.origin.type      | string  | No       | Origin platform type                               |
| external\_user\_data.origin.id        | string  | No       | Origin copilot ID                                  |
| external\_user\_data.origin.name      | string  | No       | Origin copilot name                                |
| external\_user\_data.user.id          | string  | No       | User ID                                            |
| external\_user\_data.user.name        | string  | No       | User display name                                  |
| external\_user\_data.external\_thread | string  | No       | External thread ID                                 |
| history\_size                         | integer | No       | Number of conversation history messages to include |

***

#### Submit Feedback

Submits user feedback on a specific copilot response.

| Endpoint | POST /api/copilot/{id}/{qid}/feedback |
| -------- | ------------------------------------- |
| Auth     | x-api-key, x-api-token, x-origin      |

Path Parameters:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| id        | string | Yes      | Unique identifier of the copilot        |
| qid       | string | Yes      | Unique identifier of the query/response |

Request Body Fields:

| Field | Type    | Required | Description                                      |
| ----- | ------- | -------- | ------------------------------------------------ |
| vote  | integer | Yes      | Feedback vote: 1 (thumbs up) or -1 (thumbs down) |

***

#### Generate Presigned URL

Generates a presigned URL for file access related to a copilot interaction.

| Endpoint | POST /api/copilot/presigned\_url |
| -------- | -------------------------------- |
| Auth     | x-api-key, x-api-token, x-origin |

Request Body Fields:

| Field                | Type   | Required | Description                      |
| -------------------- | ------ | -------- | -------------------------------- |
| item\_id             | string | Yes      | Item identifier                  |
| copilot\_id          | string | Yes      | Copilot identifier               |
| source\_type         | string | Yes      | Source type (e.g., s3\_manifest) |
| source               | string | Yes      | Full source path (e.g., S3 URI)  |
| external\_user\_data | object | No       | External user context data       |

Response Fields (200):

| Field | Type   | Description                 |
| ----- | ------ | --------------------------- |
| url   | string | The generated presigned URL |

***

#### Get OAuth2 Tools

Retrieves all REST API tools with OAuth2 authentication configured for a specific copilot, grouped by agent names.

| Endpoint | GET /api/copilot/{id}/oauth2\_tools |
| -------- | ----------------------------------- |
| Auth     | x-api-key, x-origin                 |

Path Parameters:

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| id        | string | Yes      | Unique identifier for the copilot |

Query Parameters:

| Parameter  | Type   | Required | Description                        |
| ---------- | ------ | -------- | ---------------------------------- |
| thread\_id | string | No       | Optional thread ID for the session |

Response Fields (200):

Returns a nested object grouped by agent name → tool name:

| Field                                 | Type   | Description              |
| ------------------------------------- | ------ | ------------------------ |
| {agent\_name}.{tool\_name}.base\_url  | string | Base URL for the API     |
| {agent\_name}.{tool\_name}.auth\_url  | string | OAuth2 authorization URL |
| {agent\_name}.{tool\_name}.token\_url | string | OAuth2 token URL         |

***

#### List Chat History

Returns a paginated list of chat request records for a specific copilot with filtering support.

| Endpoint | GET /api/copilot/{id}/history |
| -------- | ----------------------------- |
| Auth     | x-api-key, x-origin           |

Path Parameters:

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| id        | string | Yes      | Unique identifier for the copilot |

Query Parameters:

| Parameter   | Type              | Required | Default        | Description                                         |
| ----------- | ----------------- | -------- | -------------- | --------------------------------------------------- |
| skip        | integer           | No       | 0              | Number of records to skip for pagination            |
| limit       | integer           | No       | 10             | Max records to return (max 100)                     |
| sort        | string (JSON)     | No       | {"created":-1} | Sort object (e.g., {"created":1} for oldest first)  |
| status      | string            | No       | —              | Filter by status: success, failed, blocked, aborted |
| search      | string            | No       | —              | Search term to filter by input or response content  |
| start\_date | string (ISO 8601) | No       | —              | Filter records created on or after this date        |
| end\_date   | string (ISO 8601) | No       | —              | Filter records created on or before this date       |

Response Fields (200):

| Field                         | Type     | Description                             |
| ----------------------------- | -------- | --------------------------------------- |
| status                        | integer  | 1 for success                           |
| data.total                    | integer  | Total number of matching records        |
| data.skip                     | integer  | Number of records skipped               |
| data.limit                    | integer  | Max records per page                    |
| data.count                    | integer  | Number of records in this response      |
| data.data\[].\_id             | string   | Unique chat request identifier          |
| data.data\[].input            | string   | User's question or input                |
| data.data\[].response         | string   | Copilot's response                      |
| data.data\[].status           | string   | Request status                          |
| data.data\[].feedback         | object   | User feedback on the response           |
| data.data\[].tokens           | integer  | Total tokens used                       |
| data.data\[].input\_tokens    | integer  | Number of input tokens                  |
| data.data\[].output\_tokens   | integer  | Number of output tokens                 |
| data.data\[].response\_type   | string   | Type of response                        |
| data.data\[].references       | array    | Source references used                  |
| data.data\[].thread           | string   | Thread identifier                       |
| data.data\[].metadata         | object   | Request metadata (route, tags, context) |
| data.data\[].topics\_analysis | object   | Topic analysis results                  |
| data.data\[].created          | datetime | When the request was created            |
| data.data\[].modified         | datetime | When the request was last modified      |

***

### Webhooks

Webhooks allow external systems to trigger recipe processing via HTTP requests. They support file uploads, OCR, transcription, PII masking, and various connector types.

#### Create Webhook Request

Triggers a recipe run via webhook with optional file processing capabilities.

| Endpoint | POST /api/webhook/recipe/{id}    |
| -------- | -------------------------------- |
| Auth     | x-api-key, x-api-token, x-origin |

Path Parameters:

| Parameter | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| id        | string | Yes      | Unique identifier for the webhook recipe |

Query Parameters:

| Parameter          | Type   | Required | Description                                                         |
| ------------------ | ------ | -------- | ------------------------------------------------------------------- |
| published\_version | string | No       | Published version to use (e.g., "V1"). Defaults to deployed version |

Request Body Fields:

| Field                                 | Type    | Required    | Description                                                    |
| ------------------------------------- | ------- | ----------- | -------------------------------------------------------------- |
| input\_message                        | string  | Yes         | The input message/question for the recipe                      |
| file\_path                            | array   | No          | Array of file objects to process                               |
| file\_path\[].content\_type           | string  | Yes         | MIME type (e.g., application/pdf, text/plain)                  |
| file\_path\[].file\_name              | string  | Yes         | File name                                                      |
| file\_path\[].file\_content           | string  | Conditional | Base64-encoded file content                                    |
| file\_path\[].file\_path              | string  | Conditional | S3 path to the file                                            |
| file\_path\[].text                    | string  | Conditional | Plain text content                                             |
| bucket                                | string  | No          | S3 bucket name                                                 |
| object\_key\_path                     | string  | No          | S3 object key path                                             |
| metadata                              | object  | No          | Custom metadata (e.g., ticket\_id)                             |
| connector.enabled                     | boolean | No          | Whether to use a connector                                     |
| connector.connector\_type             | string  | No          | Connector type: aws or in\_memory\_base64                      |
| processing.ocr.enabled                | boolean | No          | Enable OCR processing                                          |
| processing.ocr.method                 | string  | No          | OCR method: Unstructured-IO, PyMuPDF, textract, tesseract, vlm |
| processing.ocr.extract\_images        | boolean | No          | Extract images from documents                                  |
| processing.ocr.extract\_layouts       | boolean | No          | Extract layouts (Textract only)                                |
| processing.ocr.extract\_tables        | boolean | No          | Extract tables (Textract only)                                 |
| processing.ocr.extract\_forms         | boolean | No          | Extract forms (Textract only)                                  |
| processing.ocr.fallback\_to\_textract | boolean | No          | Fallback to Textract on failure (PyMuPDF)                      |
| processing.ocr.vlm\_prompt\_template  | string  | No          | Custom VLM prompt template                                     |
| processing.transcription.enabled      | boolean | No          | Enable audio transcription                                     |
| processing.transcription.method       | string  | No          | Transcription method (e.g., default)                           |
| processing.transcription.llm          | string  | No          | LLM model ID for transcription                                 |
| processing.pii\_masking.enabled       | boolean | No          | Enable PII masking                                             |
| processing.pii\_masking.language      | string  | No          | Language code (e.g., en)                                       |
| processing.pii\_masking.entities      | object  | No          | Map of PII entity types to enable/disable                      |

Supported PII Entities:

ADDRESS, AGE, AWS\_ACCESS\_KEY, AWS\_SECRET\_KEY, CREDIT\_DEBIT\_CVV, CREDIT\_DEBIT\_EXPIRY, CREDIT\_DEBIT\_NUMBER, DATE\_TIME, DRIVER\_ID, EMAIL, INTERNATIONAL\_BANK\_ACCOUNT\_NUMBER, IP\_ADDRESS, LICENSE\_PLATE, MAC\_ADDRESS, NAME, PASSWORD, PHONE, PIN, SWIFT\_CODE, URL, USERNAME, VEHICLE\_IDENTIFICATION\_NUMBER

Response Fields (200):

| Field         | Type   | Description                           |
| ------------- | ------ | ------------------------------------- |
| batch\_status | string | Status: inProgress                    |
| request\_id   | string | Unique request identifier for polling |
| recipe\_id    | string | Recipe identifier                     |

***

#### Get Webhook Request Status

Retrieves the details and status of a specific webhook request.

| Endpoint | GET /api/webhook/request/{request\_id} |
| -------- | -------------------------------------- |
| Auth     | x-api-key, x-api-token, x-origin       |

Path Parameters:

| Parameter   | Type   | Required | Description                               |
| ----------- | ------ | -------- | ----------------------------------------- |
| request\_id | string | Yes      | Unique identifier for the webhook request |

Response Fields (200):

| Field       | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| request\_id | string | Unique identifier of the webhook request |
| status      | string | Status of the request (e.g., completed)  |
| payload     | object | Detailed payload of the webhook request  |

***

#### List Webhook Requests by Recipe

Retrieves a list of webhook requests for a specific recipe with time-based filtering.

| Endpoint | GET /api/webhook/recipe/{recipe\_id} |
| -------- | ------------------------------------ |
| Auth     | x-api-key, x-api-token, x-origin     |

Path Parameters:

| Parameter  | Type   | Required | Description                      |
| ---------- | ------ | -------- | -------------------------------- |
| recipe\_id | string | Yes      | Unique identifier for the recipe |

Query Parameters:

| Parameter   | Type              | Required | Default | Description                          |
| ----------- | ----------------- | -------- | ------- | ------------------------------------ |
| start\_time | string (ISO 8601) | No       | —       | Start of time range filter           |
| end\_time   | string (ISO 8601) | No       | —       | End of time range filter             |
| limit       | integer           | No       | 10      | Maximum number of webhooks to return |

Response Fields (200):

| Field                   | Type     | Description                    |
| ----------------------- | -------- | ------------------------------ |
| recipe\_id              | string   | Recipe ID                      |
| webhooks                | array    | List of webhook objects        |
| webhooks\[].webhook\_id | string   | Unique webhook identifier      |
| webhooks\[].timestamp   | datetime | When the webhook was triggered |
| webhooks\[].payload     | object   | Webhook payload data           |

***

### Search

#### Dataset Search

Performs a dataset search with configurable query modes including text and image search.

| Endpoint | POST /api/search |
| -------- | ---------------- |
| Auth     | x-api-key        |

Request Body Fields:

| Field             | Type    | Required    | Description                                                     |
| ----------------- | ------- | ----------- | --------------------------------------------------------------- |
| datasetId         | string  | Yes         | Unique identifier for the dataset                               |
| query.mode        | string  | Yes         | Query mode: text, image, or image\_text                         |
| query.text        | string  | Conditional | Search query text (required for text and image\_text modes)     |
| query.top\_k      | integer | No          | Number of top results to return (default: 5)                    |
| query.image\_data | string  | Conditional | Base64-encoded image (required for image and image\_text modes) |
| query.mime\_type  | string  | Conditional | MIME type of the image (e.g., image/png)                        |

Response Fields (200):

| Field                                         | Type    | Description                             |
| --------------------------------------------- | ------- | --------------------------------------- |
| results                                       | array   | Array of search result objects          |
| results\[].page\_content                      | string  | Content of the matched document segment |
| results\[].metadata.dataset\_id               | string  | Dataset identifier                      |
| results\[].metadata.item\_id                  | string  | Item identifier                         |
| results\[].metadata.main\_source\_ref         | string  | Primary source reference (e.g., S3 URI) |
| results\[].metadata.relevance\_score          | number  | Relevance score of the result           |
| results\[].metadata.file\_type                | string  | File type (e.g., pdf)                   |
| results\[].metadata.page\_number              | string  | Page number in the source document      |
| results\[].metadata.\_language\_code          | string  | Language code                           |
| results\[].metadata.\_document\_title         | string  | Document title                          |
| results\[].metadata.connector\_type           | string  | Connector type (e.g., amazon\_s3)       |
| results\[].metadata.source\_ref               | string  | Source reference path                   |
| results\[].metadata.segmentStartSeconds       | integer | Segment start time (for audio/video)    |
| results\[].metadata.segmentEndSeconds         | integer | Segment end time (for audio/video)      |
| stats.vector\_search\_exec\_time              | number  | Vector search execution time (ms)       |
| stats.creating\_query\_embeddings\_exec\_time | number  | Embedding creation time (ms)            |
| stats.embeddings\_input\_tokens               | integer | Number of input tokens for embeddings   |
| request\_id                                   | string  | Request identifier                      |

***

### Traces

#### Get Trace by Request ID

Retrieves trace/observability information for a specific request, including process details, durations, and attributes.

| Endpoint | GET /api/trace/{request\_id} |
| -------- | ---------------------------- |
| Auth     | x-api-key                    |

Path Parameters:

| Parameter   | Type   | Required | Description                        |
| ----------- | ------ | -------- | ---------------------------------- |
| request\_id | string | Yes      | The request ID to fetch traces for |

Response Fields (200):

| Field                                     | Type    | Description                          |
| ----------------------------------------- | ------- | ------------------------------------ |
| status                                    | integer | 1 for success                        |
| data                                      | array   | Array of trace span objects          |
| data\[].request\_id                       | string  | Request identifier                   |
| data\[].process                           | string  | Process name (e.g., llm\_processing) |
| data\[].duration                          | number  | Duration in seconds                  |
| data\[].timestamp                         | string  | Timestamp of the trace               |
| data\[].span\_id                          | string  | Span identifier                      |
| data\[].parent\_span\_id                  | string  | Parent span identifier               |
| data\[].details.prompt.input              | string  | Input prompt                         |
| data\[].details.prompt.output             | object  | Formatted JSON output                |
| data\[].details.prompt.reasoning\_content | string  | Reasoning content                    |
| data\[].details.attributes                | object  | Additional trace attributes          |

***

### Error Responses

All endpoints follow a consistent error response format:

| HTTP Code | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| 400       | Bad request — invalid parameters or validation error              |
| 401       | Unauthorized — invalid or missing API key/token                   |
| 403       | Forbidden — insufficient permissions or cross-organization access |
| 404       | Not found — resource does not exist                               |
| 500       | Internal server error                                             |

Standard Error Response:

{

&#x20; "status": 0,

&#x20; "message": "Error description"

}

***

### Rate Limits

Contact your account administrator for information about rate limits applicable to your plan.

***

### SDKs & Tools

* Swagger UI: Access the interactive API documentation at /docs on your Karini AI instance

OpenAPI Spec: Available via GET /api/docs for generating client libraries
