### Kolosal API Key Authentication Example

Source: https://api.kolosal.ai/docs/index

This example demonstrates how to authenticate requests to the Kolosal AI API using an API key. The key must be provided in the 'Authorization' header as a 'Bearer' token, starting with the 'kol__' prefix. This is the default authentication method for most endpoints.

```shell
curl https://api.kolosal.ai/some/endpoint \
  --header 'Authorization: Bearer kol__your_api_key_here'
```

--------------------------------

### GET /v1/models

Source: https://api.kolosal.ai/docs/index

Retrieves a list of available models. Requires API key authentication.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of available models. Requires API key authentication.

### Method
GET

### Endpoint
/v1/models

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```shell
curl https://api.kolosal.ai/v1/models \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **data** (array) - A list of available models.
  - **id** (string) - The ID of the model.
  - **object** (string) - The type of object (e.g., 'model').
  - **owned_by** (string) - The entity that owns the model.

#### Response Example
```json
{
  "data": [
    {
      "id": "gpt-3.5-turbo",
      "object": "model",
      "owned_by": "openai"
    },
    {
      "id": "kolosal-vision-1.0",
      "object": "model",
      "owned_by": "kolosal"
    }
  ]
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### GET /v1/agent/tools

Source: https://api.kolosal.ai/docs/index

Retrieves a list of tools available for the Kolosal Agent. Requires API key authentication.

```APIDOC
## GET /v1/agent/tools

### Description
Retrieves a list of tools available for the Kolosal Agent. Requires API key authentication.

### Method
GET

### Endpoint
/v1/agent/tools

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```shell
curl https://api.kolosal.ai/v1/agent/tools \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **tools** (array) - A list of available tools.
  - **name** (string) - The name of the tool.
  - **description** (string) - A description of what the tool does.

#### Response Example
```json
{
  "tools": [
    { "name": "calculator", "description": "Performs mathematical calculations." },
    { "name": "web_search", "description": "Searches the web for information." },
    { "name": "document_reader", "description": "Reads and interprets documents." }
  ]
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### GET /v1/agent/stats

Source: https://api.kolosal.ai/docs/index

Retrieves statistics for the Kolosal Agent. Requires API key authentication.

```APIDOC
## GET /v1/agent/stats

### Description
Retrieves statistics for the Kolosal Agent. Requires API key authentication.

### Method
GET

### Endpoint
/v1/agent/stats

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```shell
curl https://api.kolosal.ai/v1/agent/stats \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **total_requests** (integer) - Total number of requests processed by the agent.
- **successful_requests** (integer) - Number of successfully processed requests.
- **error_rate** (number) - The rate of errors encountered.
- **average_response_time_ms** (integer) - Average response time in milliseconds.

#### Response Example
```json
{
  "total_requests": 15000,
  "successful_requests": 14500,
  "error_rate": 0.033,
  "average_response_time_ms": 250
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### GET /health/detailed

Source: https://api.kolosal.ai/docs/index

Performs a detailed health check on the service, providing more insights into its operational status.

```APIDOC
## GET /health/detailed

### Description
Performs a detailed health check on the service, providing more insights into its operational status.

### Method
GET

### Endpoint
/health/detailed

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```shell
curl https://api.kolosal.ai/health/detailed \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service, e.g., "healthy".
- **timestamp** (string) - The timestamp when the health check was performed.
- **memory_usage_mb** (integer) - The current memory usage of the service in megabytes.
- **uptime_seconds** (integer) - The uptime of the service in seconds.
- **version** (string) - The version of the service.

#### Response Example
```json
{
  "memory_usage_mb": 128,
  "status": "healthy",
  "timestamp": "2025-10-25T10:30:00Z",
  "uptime_seconds": 3600,
  "version": "0.1.0"
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### GET /health

Source: https://api.kolosal.ai/docs/index

Performs a health check on the service. Returns a status indicating if the service is operational.

```APIDOC
## GET /health

### Description
Performs a health check on the service. Returns a status indicating if the service is operational.

### Method
GET

### Endpoint
/health

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```shell
curl https://api.kolosal.ai/health \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the service, e.g., "healthy".
- **timestamp** (string) - The timestamp when the health check was performed.

#### Response Example
```json
{
  "status": "healthy",
  "timestamp": "2025-10-25T10:30:00Z"
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### Get Detailed API Health Information

Source: https://api.kolosal.ai/docs/index

This endpoint provides detailed health information about the Kolosal AI service, including memory usage, status, timestamp, uptime, and version. API key authentication is required. A successful response (200) includes these details, while invalid or missing API keys result in a 401 error.

```shell
curl https://api.kolosal.ai/health/detailed \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```

--------------------------------

### POST /v1/chat/completions

Source: https://api.kolosal.ai/docs/index

Provides chat completion functionality compatible with OpenAI's API. Requires API key authentication.

```APIDOC
## POST /v1/chat/completions

### Description
Provides chat completion functionality compatible with OpenAI's API. Requires API key authentication.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **model** (string) - The model to use for chat completion.
- **messages** (array) - A list of messages comprising the conversation.
  - **role** (string) - The role of the author of the message ('system', 'user', or 'assistant').
  - **content** (string) - The content of the message.
- **temperature** (number, optional) - Controls randomness. Higher values mean more random.
- **max_tokens** (integer, optional) - The maximum number of tokens to generate.

### Request Example
```json
{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Who won the world series in 2020?"}
  ],
  "temperature": 0.7,
  "max_tokens": 150
}
```

### Response
#### Success Response (200)
- **choices** (array) - A list of chat completion choices.
  - **message** (object) - The generated message.
    - **role** (string) - The role of the author ('assistant').
    - **content** (string) - The content of the assistant's message.
- **usage** (object) - Usage statistics for the request.
  - **prompt_tokens** (integer) - Number of tokens in the prompt.
  - **completion_tokens** (integer) - Number of tokens in the completion.
  - **total_tokens** (integer) - Total tokens used.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "The Los Angeles Dodgers won the World Series in 2020."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43
  }
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### Website API Documentation

Source: https://api.kolosal.ai/docs/index

This section details the parameters and headers used for interacting with the Kolosal AI website API. It outlines path parameters, cookies, headers, and query parameters.

```APIDOC
## /websites/api_kolosal_ai

### Description
This endpoint allows for interaction with the Kolosal AI website API, supporting various parameters and headers for requests.

### Method
(Not specified, assumed to be GET or POST based on context)

### Endpoint
/websites/api_kolosal_ai

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
- **Key** (string) - Optional - Description of the parameter.
- **Value** (string) - Optional - Description of the parameter.

#### Cookies
- **Key** (string) - Optional - Description of the cookie.
- **Value** (string) - Optional - Description of the cookie.

#### Headers
- **Accept** (string) - Optional - Defaults to `*/*`.
- **Key** (string) - Optional - Description of the header.
- **Value** (string) - Optional - Description of the header.

### Request Example
(No specific request body example provided in the source text)

### Response
#### Success Response (200)
(Response structure not detailed in the source text)

#### Response Example
(No specific response example provided in the source text)
```

--------------------------------

### POST /v1/agent/generate

Source: https://api.kolosal.ai/docs/index

Generates a response using the Kolosal Agent. Requires API key authentication.

```APIDOC
## POST /v1/agent/generate

### Description
Generates a response using the Kolosal Agent. Requires API key authentication.

### Method
POST

### Endpoint
/v1/agent/generate

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **prompt** (string) - The input prompt for the agent.
- **context** (object, optional) - Contextual information for the agent.
- **tools** (array, optional) - List of tools the agent can use.

### Request Example
```json
{
  "prompt": "Summarize the main points of the latest market trends report.",
  "context": {
    "user_id": "user123"
  },
  "tools": ["calculator", "web_search"]
}
```

### Response
#### Success Response (200)
- **response** (string) - The agent's generated response.

#### Response Example
```json
{
  "response": "The main points of the latest market trends report indicate a significant growth in the renewable energy sector and a moderate increase in consumer spending on digital services."
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### Workspace Management API

Source: https://api.kolosal.ai/docs/index

Endpoints for managing workspaces, including creation, retrieval, updating, and deletion. Requires API key authentication.

```APIDOC
## Workspace Management API

### Description
Endpoints for managing workspaces, including creation, retrieval, updating, and deletion. Requires API key authentication.

### Endpoints

#### GET /v1/workspaces
- Retrieves a list of all workspaces.

#### POST /v1/workspaces
- Creates a new workspace.
  - **Request Body**:
    - **name** (string) - The name of the new workspace.

#### GET /v1/workspaces/order
- Retrieves the order of workspaces.

#### PUT /v1/workspaces/order
- Updates the order of workspaces.
  - **Request Body**:
    - **workspace_ids** (array) - An array of workspace IDs in the desired order.

#### GET /v1/workspaces/order/stats
- Retrieves statistics related to workspace ordering.

#### GET /v1/workspaces/stats
- Retrieves general statistics for all workspaces.

#### GET /v1/workspaces/{workspace_id}
- Retrieves details for a specific workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace to retrieve.

#### DELETE /v1/workspaces/{workspace_id}
- Deletes a specific workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace to delete.

#### PATCH /v1/workspaces/{workspace_id}
- Updates a specific workspace (partial update).
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace to update.
  - **Request Body**:
    - **name** (string, optional) - The new name for the workspace.

#### GET /v1/workspaces/{workspace_id}/categories
- Retrieves categories within a specific workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.

#### POST /v1/workspaces/{workspace_id}/categories
- Creates a new category within a specific workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
  - **Request Body**:
    - **name** (string) - The name of the new category.

#### GET /v1/workspaces/{workspace_id}/categories/order
- Retrieves the order of categories within a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.

#### PUT /v1/workspaces/{workspace_id}/categories/order
- Updates the order of categories within a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
  - **Request Body**:
    - **category_ids** (array) - An array of category IDs in the desired order.

#### GET /v1/workspaces/{workspace_id}/categories/{category_id}
- Retrieves details for a specific category within a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category.

#### DELETE /v1/workspaces/{workspace_id}/categories/{category_id}
- Deletes a specific category within a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category to delete.

#### PATCH /v1/workspaces/{workspace_id}/categories/{category_id}
- Updates a specific category within a workspace (partial update).
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category to update.
  - **Request Body**:
    - **name** (string, optional) - The new name for the category.

#### GET /v1/workspaces/{workspace_id}/categories/{category_id}/features
- Retrieves features within a specific category of a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category.

#### POST /v1/workspaces/{workspace_id}/categories/{category_id}/features
- Creates a new feature within a specific category of a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category.
  - **Request Body**:
    - **name** (string) - The name of the new feature.
    - **type** (string) - The type of the feature.

#### GET /v1/workspaces/{workspace_id}/categories/{category_id}/features/order
- Retrieves the order of features within a category of a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category.

#### PUT /v1/workspaces/{workspace_id}/categories/{category_id}/features/order
- Updates the order of features within a category of a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category.
  - **Request Body**:
    - **feature_ids** (array) - An array of feature IDs in the desired order.

#### GET /v1/workspaces/{workspace_id}/categories/{category_id}/features/{feature_id}
- Retrieves details for a specific feature within a category of a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category.
    - **feature_id** (string) - The ID of the feature.

#### DELETE /v1/workspaces/{workspace_id}/categories/{category_id}/features/{feature_id}
- Deletes a specific feature within a category of a workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category.
    - **feature_id** (string) - The ID of the feature to delete.

#### PATCH /v1/workspaces/{workspace_id}/categories/{category_id}/features/{feature_id}
- Updates a specific feature within a category of a workspace (partial update).
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.
    - **category_id** (string) - The ID of the category.
    - **feature_id** (string) - The ID of the feature to update.
  - **Request Body**:
    - **name** (string, optional) - The new name for the feature.
    - **type** (string, optional) - The new type for the feature.

#### GET /v1/workspaces/{workspace_id}/status
- Retrieves the status of a specific workspace.
  - **Path Parameters**:
    - **workspace_id** (string) - The ID of the workspace.

### Response
#### Success Response (200)
Responses vary based on the specific endpoint. Generally, successful requests return relevant data or a confirmation message.

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### POST /v1/agent/generate/stream

Source: https://api.kolosal.ai/docs/index

Generates a response using the Kolosal Agent in a streaming format. Requires API key authentication.

```APIDOC
## POST /v1/agent/generate/stream

### Description
Generates a response using the Kolosal Agent in a streaming format. Requires API key authentication.

### Method
POST

### Endpoint
/v1/agent/generate/stream

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **prompt** (string) - The input prompt for the agent.
- **context** (object, optional) - Contextual information for the agent.
- **tools** (array, optional) - List of tools the agent can use.

### Request Example
```json
{
  "prompt": "Explain the concept of quantum computing in simple terms.",
  "context": {
    "user_id": "user456"
  }
}
```

### Response
#### Success Response (200)
- **stream** (string) - A stream of text chunks representing the agent's response.

#### Response Example
```json
{
  "stream": "Quantum computing is...It utilizes..."
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### Object Detection API

Source: https://api.kolosal.ai/docs/index

Provides endpoints for object detection using YOLO, SAM3, and YOLOE models. Includes caching and detection health checks. Requires API key authentication.

```APIDOC
## Object Detection API

### Description
Provides endpoints for object detection using YOLO, SAM3, and YOLOE models. Includes caching and detection health checks. Requires API key authentication.

### Endpoints

#### GET /v1/cache
- Retrieves information about the object detection cache.

#### DELETE /v1/cache
- Clears the object detection cache.

#### GET /v1/detect/health
- Performs a health check on the object detection service.

#### GET /v1/detect/stats
- Retrieves statistics for the object detection service.

#### POST /v1/segment
- Performs image segmentation using the specified model.
  - **Request Body**:
    - **image** (file) - The image to process.
    - **model** (string) - The object detection model to use (e.g., 'yolo', 'sam3', 'yoloe').
    - **classes** (array, optional) - List of classes to detect.

#### POST /v1/segment/base64
- Performs image segmentation using a base64 encoded image.
  - **Request Body**:
    - **image_base64** (string) - The base64 encoded image string.
    - **model** (string) - The object detection model to use (e.g., 'yolo', 'sam3', 'yoloe').
    - **classes** (array, optional) - List of classes to detect.

### Response
#### Success Response (200)
Responses vary based on the specific endpoint. Segmentation endpoints typically return detected objects, bounding boxes, or segmentation masks.

#### Response Example (Segmentation)
```json
{
  "detections": [
    {
      "class": "car",
      "confidence": 0.95,
      "box": [100, 150, 200, 250] // [x_min, y_min, x_max, y_max]
    }
  ]
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### POST /ocr

Source: https://api.kolosal.ai/docs/index

Processes an image using AI-powered OCR to extract structured data. Requires API key authentication.

```APIDOC
## POST /ocr

### Description
Processes an image using AI-powered OCR to extract structured data. Requires API key authentication.

### Method
POST

### Endpoint
/ocr

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **image** (file) - The image file to process.
- **config** (object, optional) - Configuration options for OCR processing.
  - **language** (string, optional) - The language of the document.
  - **output_format** (string, optional) - The desired output format (e.g., 'json', 'xml').

### Request Example
```json
{
  "image": "<base64_encoded_image>",
  "config": {
    "language": "en",
    "output_format": "json"
  }
}
```

### Response
#### Success Response (200)
- **extracted_data** (object) - The structured data extracted from the document.

#### Response Example
```json
{
  "extracted_data": {
    "invoice_number": "INV-12345",
    "total_amount": 150.75,
    "items": [
      { "description": "Product A", "quantity": 2, "price": 50.00 },
      { "description": "Product B", "quantity": 1, "price": 50.75 }
    ]
  }
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### POST /ocr/form

Source: https://api.kolosal.ai/docs/index

Processes a form image using AI-powered OCR to extract structured data, specifically designed for form recognition. Requires API key authentication.

```APIDOC
## POST /ocr/form

### Description
Processes a form image using AI-powered OCR to extract structured data, specifically designed for form recognition. Requires API key authentication.

### Method
POST

### Endpoint
/ocr/form

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **image** (file) - The form image file to process.
- **form_definition** (object, optional) - The definition of the form fields to extract.
  - **field_name** (string) - The name of the form field.
  - **bbox** (array) - Bounding box coordinates for the field.

### Request Example
```json
{
  "image": "<base64_encoded_image>",
  "form_definition": {
    "name": {"bbox": [100, 50, 300, 70]},
    "email": {"bbox": [100, 80, 300, 100]}
  }
}
```

### Response
#### Success Response (200)
- **extracted_data** (object) - The structured data extracted from the form.

#### Response Example
```json
{
  "extracted_data": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}
```

#### Error Response (401)
- **message** (string) - Describes the error, e.g., "Invalid or missing API key".

```

--------------------------------

### Check API Health Status

Source: https://api.kolosal.ai/docs/index

This endpoint checks the health status of the Kolosal AI service. It requires API key authentication. Successful requests return a JSON object with the service status and timestamp. Failed requests due to invalid or missing API keys return a 401 status code.

```shell
curl https://api.kolosal.ai/health \
  --header 'Authorization: YOUR_SECRET_TOKEN'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.