# Olly REST API

Use the **Olly REST API** to make [Olly](https://coralogix.com/docs/user-guides/olly/index.md) a programmatic participant in your AI agents, automation pipelines, and scheduled jobs. Trigger investigations from outside the Coralogix UI, send prompts on behalf of a user, and retrieve the query results, charts, and tables Olly generates — all using the same models, skills, and permissions as the in-product chat.

Common use cases include:

- Pulling Olly findings into an external agent or partner integration that enriches its workflow with observability insights.
- Exposing Olly as a tool to your own automation or AI tooling.
- Running scheduled or deployment-triggered investigations with no human in the loop.

## What you need

Olly enabled for your team. The chat and message endpoints return `403 Forbidden` until your team admin turns on the **AI-Powered Capabilities** toggle in **Settings**, then **Account Preferences**. See [Enable Olly](https://coralogix.com/docs/user-guides/olly/enable/index.md).

## Authentication

Every request requires an [API key](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/index.md), passed as a Bearer token in the `Authorization` header. The Olly API accepts two key types:

- **Personal API key**: tied to a single user. Token consumption is deducted from the user's quota.
- **Team API key**: tied to a team, intended for shared services, agents, and integrations. Token consumption is deducted from the team's quota only — no per-user limit and no free units. If the team has no paid quota, the request is blocked.

Pick the endpoint that matches your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain/index.md) using the domain selector at the top of the page.

**Example:**

```bash
curl -H "Authorization: Bearer <cx_api_key>" \
  https://api.[[DOMAIN_VALUE]]/api/v2/olly/v2/chats/
```

### Entity identity

Each chat and interaction is owned by a single **entity** — either a user or a team key. The owner is recorded in the response field `entity_id`:

| Caller           | `entity_id` value                                             |
| ---------------- | ------------------------------------------------------------- |
| Personal API key | The user's ID.                                                |
| Team API key     | `team_key:<key_id>`. `key_id` is stable across key rotations. |

### Access control

Access to a chat follows its `shared_type` and the caller's `entity_id`:

| `shared_type`         | Who can access                                      |
| --------------------- | --------------------------------------------------- |
| `private` (default)   | Only the owning `entity_id`.                        |
| `specific_entities`   | Only the entity IDs listed in `shared_entity_ids`.  |
| `entire_organization` | Any entity in the team — users and team keys alike. |

A `private` chat created by a user is not accessible by a team API key, and vice versa, because their `entity_id` values differ.

## Core concepts

| Concept            | Description                                                                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chat**           | A conversation session. Create one before sending messages.                                                                                                 |
| **Interaction**    | A single user message and the AI response within a chat. Each message you send creates one interaction.                                                     |
| **Artifact**       | A structured data object — logs, spans, or metrics — the agent produces during an interaction.                                                              |
| **View**           | A visualization (chart or table) generated from artifact data.                                                                                              |
| **User file**      | A file you upload through the API and reference in a chat message to give Olly extra context.                                                               |
| **User rule**      | A personal instruction Olly applies to every chat in your session — for example, "always group log results by `service.name`."                              |
| **Team rule**      | A team-wide instruction a team admin sets. Olly applies it to every team member's chats. Managing team rules requires admin permissions.                    |
| **Personal skill** | A reusable Markdown instruction set you author for your own chats. Pre-load specific skills into a run with `load_skill_ids`.                               |
| **Team skill**     | A reusable Markdown instruction set a team admin authors. Olly considers it for every team member's chats. Managing team skills requires admin permissions. |

This document provides example requests and responses for creating chats, sending messages with the wait-for-response and polling flows, retrieving the artifacts Olly produces during an interaction, and managing your user rules, personal skills, and team skills.

This document provides example requests and responses for creating chats, sending messages with the wait-for-response and polling flows, retrieving the artifacts Olly produces during an interaction, and managing your user rules and personal skills.

### Interaction modes

Every API interaction runs in **`skill`** mode — the single Olly chat mode used in the Coralogix UI. This is the default for `interaction_mode`: Olly applies a curated set of specialized skills to each request, extensible with your own custom skills.

Deprecated modes

The API still accepts `focus` and `fast` for backwards compatibility; both route to `skill`. Migrate existing integrations to `skill` when convenient — the legacy values may be removed in a future API version.

See [Olly chat](https://coralogix.com/docs/user-guides/olly/olly-chat/index.md) for the in-product chat experience.

### Models

Use the `model_choice` field to pick the model Olly runs the interaction with. The API default is `gpt-5.4`. To match what users see in the in-product Olly chat, pass one of:

`gpt-5.4`, `gpt-5.4-mini`, `gpt-5.2`, `claude-sonnet-4-5`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `gemini-3.1-pro-preview`, `gemini-3-flash-preview`.

See [Model selection](https://coralogix.com/docs/user-guides/olly/model-selection/index.md) for the in-product display names and recommended defaults.

### Interaction status lifecycle

```
flowchart LR
    Created[Interaction created]
    InProgress[In progress]
    Completed[Completed]
    Error[Error]
    Stopped[Stopped]

    Created --> InProgress
    InProgress -->|Agent finished| Completed
    InProgress -->|Encountered an error| Error
    InProgress -->|User cancelled via /stop| Stopped

    class Created entry
    class Completed success
    class Error error
    class Stopped waiting
```

## Send a message and wait for the response

Send a message and wait for the response in a single request. Set `should_block: true` to make the call return only after the agent finishes.

### Step 1: Create a chat

**Example request:**

```text
POST /api/v2/olly/v2/chats/
```

**Example response** (`201 Created`):

```json
{
  "id": "a1b2c3d4-...",
  "title": "",
  "entity_id": "user_abc-123",
  "created_at": "2025-01-15T10:30:00Z",
  "type": "web",
  "shared_options": { "shared_type": "private", "shared_entity_ids": null },
  "metadata": null
}
```

### Step 2: Send a message (wait inline)

**Example request:**

```text
POST /api/v2/olly/v2/chats/{chat_id}/interactions/
```

```json
{
  "content": [{"type": "input_text", "text": "What alerts fired in the last hour?"}],
  "should_block": true,
  "timeout_seconds": 120
}
```

**Example response** (`200 OK`, after the agent finishes):

```json
{
  "id": "e5f6g7h8-...",
  "chat_id": "a1b2c3d4-...",
  "status": "completed",
  "interaction_mode": "skill",
  "model_choice": "gpt-5.4",
  "created_at": "2025-01-15T10:30:05Z",
  "feedback": null,
  "feedback_description": null,
  "data_sources": [],
  "responses": [
    {
      "id": "msg-user-1",
      "role": "user",
      "content": [{"type": "text", "text": "What alerts fired in the last hour?"}]
    },
    {
      "id": "msg-assistant-1",
      "role": "assistant",
      "content": [{"type": "text", "text": "I found 3 alerts that fired in the last hour..."}]
    }
  ]
}
```

## Poll for response

Send a message, then poll for the response. Use this flow when responses might take more than a few seconds, or when you want to show interim progress in your UI.

### Step 1: Create a chat

Create a chat the same way as described [here](https://coralogix.com/docs/developer-portal/apis/olly/#step-1-create-a-chat).

### Step 2: Send a message (non-blocking)

**Example request:**

```text
POST /api/v2/olly/v2/chats/{chat_id}/interactions/
```

```json
{
  "content": [{"type": "input_text", "text": "Show me error logs from the payments service"}]
}
```

**Example response** (`200 OK`, returns immediately):

```json
{
  "id": "e5f6g7h8-...",
  "chat_id": "a1b2c3d4-...",
  "status": "in_progress",
  "interaction_mode": "skill",
  "model_choice": "gpt-5.4",
  "created_at": "2025-01-15T10:30:05Z",
  "feedback": null,
  "feedback_description": null,
  "data_sources": [],
  "responses": null
}
```

### Step 3: Poll for completion

**Example request:**

```text
GET /api/v2/olly/v2/chats/{chat_id}/interactions/{interaction_id}
```

Poll every few seconds. When `status` changes to `completed`, the `responses` field contains the agent's reply.

**Example response** (`200 OK`, after `status` becomes `completed`):

```json
{
  "id": "e5f6g7h8-...",
  "chat_id": "a1b2c3d4-...",
  "status": "completed",
  "interaction_mode": "skill",
  "model_choice": "gpt-5.4",
  "created_at": "2025-01-15T10:30:05Z",
  "feedback": null,
  "feedback_description": null,
  "data_sources": [],
  "responses": [
    {
      "id": "msg-user-1",
      "role": "user",
      "content": [{"type": "text", "text": "Show me error logs from the payments service"}]
    },
    {
      "id": "msg-assistant-1",
      "role": "assistant",
      "content": [{"type": "text", "text": "Here are the recent error logs from the payments service..."}]
    }
  ]
}
```

## Attach files to a message

To include a file in a chat message, upload it first and then pass the returned file IDs in `user_file_ids` on the create-interaction request. The upload flow uses a presigned URL so file bytes go directly to cloud storage, not through the API.

### Step 1: Check upload options

**Example request:**

```text
GET /api/v2/olly/user-files/upload-options
```

**Example response** (`200 OK`):

```json
{
  "allowed_content_types": ["application/pdf", "image/png", "image/jpeg", "text/csv", "..."],
  "max_file_size_bytes": 5242880,
  "max_plaintext_total_size_bytes": 1048576,
  "max_files_per_message": 5,
  "plaintext_content_types": ["text/plain", "application/json", "text/csv", "..."]
}
```

Use this to check the current size and count limits, and the content types Olly accepts, before requesting an upload URL.

### Step 2: Request a presigned upload URL

**Example request:**

```text
POST /api/v2/olly/user-files/upload-url
```

```json
{
  "file_name": "alerts-2026-05-15.csv",
  "content_type": "text/csv"
}
```

**Example response** (`201 Created`):

```json
{
  "user_file_id": "f7e6d5c4-...",
  "presigned_post": {
    "url": "https://storage.example.com/uploads",
    "fields": {
      "key": "user-files/f7e6d5c4-...",
      "policy": "eyJleHBpcmF0aW9uIjogIjIw...",
      "x-amz-signature": "abc123...",
      "x-amz-credential": "..."
    }
  }
}
```

### Step 3: Upload the file to cloud storage

POST the file as a multipart form to `presigned_post.url`, including every key/value from `presigned_post.fields` and the file bytes in a `file` field:

```bash
curl -X POST <presigned_post.url> \
  -F key=<presigned_post.fields.key> \
  -F policy=<presigned_post.fields.policy> \
  -F x-amz-signature=<presigned_post.fields.x-amz-signature> \
  -F x-amz-credential=<presigned_post.fields.x-amz-credential> \
  -F file=@/path/to/alerts-2026-05-15.csv
```

A successful upload returns `204 No Content` from cloud storage.

### Step 4: Attach the file in your message

Pass the `user_file_id` returned in Step 2 on the create-interaction request:

**Example request:**

```text
POST /api/v2/olly/v2/chats/{chat_id}/interactions/
```

```json
{
  "content": [{"type": "input_text", "text": "Summarize the alerts in the attached CSV."}],
  "user_file_ids": ["f7e6d5c4-..."]
}
```

To retrieve a previously uploaded file later, use:

```text
GET /api/v2/olly/user-files/{user_file_id}/download_url
```

For the in-product file-attachment UX (file types, size limits, behavior in chat), see [File attachments for chat context](https://coralogix.com/docs/user-guides/olly/file-attachments/index.md).

## Manage artifacts

After an interaction completes, retrieve any artifacts the agent produced (query results, charts) through the artifacts endpoints.

### List artifacts for a chat

**Example request:**

```text
GET /api/v2/olly/artifacts/?chat_id={chat_id}
```

**Example response** (`200 OK`):

```json
[
  {
    "id": "art-1234-...",
    "created_at": "2025-01-15T10:30:10Z",
    "type": "coralogix_logs",
    "chat_id": "a1b2c3d4-...",
    "interaction_id": "e5f6g7h8-...",
    "is_user_managed": false,
    "data_source_id": null,
    "chat_title": "Alert Investigation",
    "chat_type": "web"
  }
]
```

### Get an artifact with download URL

**Example request:**

```text
GET /api/v2/olly/artifacts/{artifact_id}
```

**Example response** (`200 OK`):

```json
{
  "id": "art-1234-...",
  "type": "coralogix_logs",
  "params": {
    "query": "source logs | filter severity == 'error' | filter $d.service == 'payments'",
    "description": "Error logs from payments service"
  },
  "download_url": "https://storage.example.com/...",
  "created_at": "2025-01-15T10:30:10Z",
  "chat_id": "a1b2c3d4-...",
  "interaction_id": "e5f6g7h8-...",
  "is_user_managed": false,
  "data_source_id": null
}
```

The `download_url` is a pre-signed URL that gives temporary access to the full artifact data, stored as gzipped JSON.

### Get views (charts and tables) for an artifact

**Example request:**

```text
GET /api/v2/olly/views/artifacts/{artifact_id}
```

**Example response** (`200 OK`):

```json
[
  {
    "id": "view-5678-...",
    "type": "chart",
    "artifact_ids": ["art-1234-..."],
    "download_url": "https://storage.example.com/...",
    "created_at": "2025-01-15T10:30:15Z",
    "team_id": "team123"
  }
]
```

## Manage user rules

User rules are personal instructions Olly applies to every chat. See [Rules](https://coralogix.com/docs/user-guides/olly/rules/index.md) for the in-product UX, validation, and limits.

**Example request:** create a personal rule

```text
POST /api/v2/olly/user-rules/
```

```json
{
  "rule": "When summarizing logs, group entries by `service.name` and surface the top three error categories per service."
}
```

**Example response** (`201 Created`):

```json
{
  "id": "9f8e7d6c-...",
  "rule": "When summarizing logs, group entries by `service.name` and surface the top three error categories per service.",
  "enabled": true,
  "created_at": "2026-05-27T10:30:00Z"
}
```

See [User rules](#user-rules) in the Endpoint reference for `GET`, `PUT`, and `DELETE` operations.

## Manage team rules

Team rules are instructions a team admin defines and Olly applies for every team member. The endpoint shape mirrors user rules; the difference is scope and permissions — creating, updating, or deleting a team rule requires admin permissions. See [Rules](https://coralogix.com/docs/user-guides/olly/rules/#team-rules) for the in-product UX and the permission keys.

**Example request:** create a team rule

```text
POST /api/v2/olly/team-rules/
```

```json
{
  "rule": "When investigating incidents, prioritize production environments over staging."
}
```

**Example response** (`201 Created`):

```json
{
  "id": "4e3d2c1b-...",
  "rule": "When investigating incidents, prioritize production environments over staging.",
  "enabled": true,
  "created_at": "2026-05-27T10:30:00Z"
}
```

See [Team rules](#team-rules) in the Endpoint reference for `GET`, `PUT`, and `DELETE` operations.

## Manage personal skills

Personal skills are reusable Markdown instruction sets you can pre-load into a Skills Agent run with `load_skill_ids`. See [Skills](https://coralogix.com/docs/user-guides/olly/skills/index.md) for the in-product UX, naming rules, validation, and limits.

### Create a personal skill

**Example request:**

```text
POST /api/v2/olly/skills/personal/
```

```json
{
  "name": "log-summarizer",
  "description": "Summarize the last hour of logs by service.",
  "content": "When this skill is invoked, group log entries by `service.name` and surface the top three error categories per service."
}
```

**Example response** (`201 Created`):

```json
{
  "id": "5a4b3c2d-...",
  "name": "log-summarizer",
  "description": "Summarize the last hour of logs by service.",
  "content": "When this skill is invoked, group log entries by `service.name` and surface the top three error categories per service.",
  "enabled": true,
  "created_at": "2026-05-27T10:30:00Z",
  "entity_id": "user_abc-123"
}
```

Constraints: `name` ≤ 64 characters, `description` ≤ 1024 characters, `content` ≤ 20480 characters.

### List personal skills

**Example request:**

```text
GET /api/v2/olly/skills/personal/
```

**Example response** (`200 OK`):

```json
[
  {
    "id": "5a4b3c2d-...",
    "name": "log-summarizer",
    "description": "Summarize the last hour of logs by service.",
    "content": "When this skill is invoked, group log entries by `service.name` and surface the top three error categories per service.",
    "enabled": true,
    "created_at": "2026-05-27T10:30:00Z",
    "entity_id": "user_abc-123"
  }
]
```

See [Skills](#skills) in the Endpoint reference for `PUT` and `DELETE` operations.

## Manage team skills

Team skills are reusable Markdown instruction sets a team admin defines and Olly considers for every team member's chats. The endpoint shape mirrors personal skills; the difference is scope and permissions — creating, updating, or deleting a team skill requires admin permissions. See [Skills](https://coralogix.com/docs/user-guides/olly/skills/index.md) for the in-product UX, naming rules, and limits.

**Example request:** create a team skill

```text
POST /api/v2/olly/skills/team/
```

```json
{
  "name": "incident-retrospective",
  "description": "Draft a retrospective from a closed incident's alerts and logs.",
  "content": "When this skill is invoked, summarize the incident's alerts, timeline, and contributing factors using the team's retrospective template."
}
```

**Example response** (`201 Created`):

```json
{
  "id": "9f8e7d6c-...",
  "name": "incident-retrospective",
  "description": "Draft a retrospective from a closed incident's alerts and logs.",
  "content": "When this skill is invoked, summarize the incident's alerts, timeline, and contributing factors using the team's retrospective template.",
  "enabled": true,
  "created_at": "2026-05-27T10:30:00Z",
  "entity_id": null
}
```

Team skills are not owned by an entity, so `entity_id` is `null` in responses.

To pre-load team skills into an interaction, pass their IDs in the `load_skill_ids` field on the create-interaction request — the same field used for personal skills.

See [Skills](#skills) in the Endpoint reference for the full set of `GET`, `PUT`, and `DELETE` operations.

## Endpoint reference

### Chats

| Method   | Path                                     | Description                               |
| -------- | ---------------------------------------- | ----------------------------------------- |
| `POST`   | `/api/v2/olly/v2/chats/`                 | Create a new chat                         |
| `GET`    | `/api/v2/olly/v2/chats/`                 | List all chats for the current user       |
| `GET`    | `/api/v2/olly/v2/chats/{chat_id}`        | Get a chat with full conversation history |
| `GET`    | `/api/v2/olly/v2/chats/search`           | Search chats by content                   |
| `GET`    | `/api/v2/olly/v2/chats/{chat_id}/title`  | Get a chat's title                        |
| `PATCH`  | `/api/v2/olly/v2/chats/{chat_id}/title`  | Rename a chat                             |
| `DELETE` | `/api/v2/olly/v2/chats/{chat_id}`        | Delete a chat and all associated data     |
| `PATCH`  | `/api/v2/olly/v2/chats/{chat_id}/shared` | Set chat privacy and sharing options      |
| `POST`   | `/api/v2/olly/v2/chats/{chat_id}/stop`   | Stop an ongoing response generation       |

### Interactions

| Method | Path                                                            | Description                            |
| ------ | --------------------------------------------------------------- | -------------------------------------- |
| `POST` | `/api/v2/olly/v2/chats/{chat_id}/interactions/`                 | Send a message (create an interaction) |
| `GET`  | `/api/v2/olly/v2/chats/{chat_id}/interactions/`                 | List interactions in a chat            |
| `GET`  | `/api/v2/olly/v2/chats/{chat_id}/interactions/{interaction_id}` | Get interaction status and responses   |

### User files

| Method | Path                                                  | Description                                       |
| ------ | ----------------------------------------------------- | ------------------------------------------------- |
| `GET`  | `/api/v2/olly/user-files/upload-options`              | Get current size, count, and content-type limits  |
| `POST` | `/api/v2/olly/user-files/upload-url`                  | Mint a presigned upload URL for a new file        |
| `GET`  | `/api/v2/olly/user-files/{user_file_id}/download_url` | Get a download URL for a previously uploaded file |

### User rules

User rules are personal instructions Olly applies to every chat. See [Rules](https://coralogix.com/docs/user-guides/olly/rules/index.md) for the in-product UX.

| Method   | Path                                | Description                   |
| -------- | ----------------------------------- | ----------------------------- |
| `GET`    | `/api/v2/olly/user-rules/`          | List the current user's rules |
| `POST`   | `/api/v2/olly/user-rules/`          | Create a new user rule        |
| `GET`    | `/api/v2/olly/user-rules/{rule_id}` | Get a specific rule           |
| `PUT`    | `/api/v2/olly/user-rules/{rule_id}` | Update a rule                 |
| `DELETE` | `/api/v2/olly/user-rules/{rule_id}` | Delete a rule                 |

### Team rules

Team rules are instructions a team admin defines and Olly applies for every team member. Managing team rules requires admin permissions. See [Rules](https://coralogix.com/docs/user-guides/olly/rules/#team-rules) for the in-product UX and permission details.

| Method   | Path                                | Description                    |
| -------- | ----------------------------------- | ------------------------------ |
| `GET`    | `/api/v2/olly/team-rules/`          | List team rules                |
| `POST`   | `/api/v2/olly/team-rules/`          | Create a new team rule (admin) |
| `GET`    | `/api/v2/olly/team-rules/{rule_id}` | Get a specific team rule       |
| `PUT`    | `/api/v2/olly/team-rules/{rule_id}` | Update a team rule (admin)     |
| `DELETE` | `/api/v2/olly/team-rules/{rule_id}` | Delete a team rule (admin)     |

### Skills

Skills are reusable instruction sets Olly can apply mid-chat. The API exposes two scopes — **personal** skills owned by the calling user, and **team** skills shared across the team. Team-skill writes require admin permissions. See [Skills](https://coralogix.com/docs/user-guides/olly/skills/index.md) for the in-product UX, naming rules, and limits.

| Method   | Path                                      | Description                               |
| -------- | ----------------------------------------- | ----------------------------------------- |
| `GET`    | `/api/v2/olly/skills/personal/`           | List the current user's personal skills   |
| `POST`   | `/api/v2/olly/skills/personal/`           | Create a personal skill                   |
| `PUT`    | `/api/v2/olly/skills/personal/{skill_id}` | Update a personal skill                   |
| `DELETE` | `/api/v2/olly/skills/personal/{skill_id}` | Delete a personal skill                   |
| `GET`    | `/api/v2/olly/skills/team/`               | List team skills, including disabled ones |
| `POST`   | `/api/v2/olly/skills/team/`               | Create a team skill (admin)               |
| `PUT`    | `/api/v2/olly/skills/team/{skill_id}`     | Update a team skill (admin)               |
| `DELETE` | `/api/v2/olly/skills/team/{skill_id}`     | Delete a team skill (admin)               |

To pre-load specific skills (personal or team) into a Skills Agent run, pass their IDs in the `load_skill_ids` field on the create-interaction request (see [Request body: create interaction](#request-body-create-interaction)).

### Artifacts

| Method | Path                                   | Description                          |
| ------ | -------------------------------------- | ------------------------------------ |
| `GET`  | `/api/v2/olly/artifacts/`              | List artifacts with optional filters |
| `GET`  | `/api/v2/olly/artifacts/{artifact_id}` | Get an artifact with download URL    |

### Artifact views

| Method | Path                                         | Description                |
| ------ | -------------------------------------------- | -------------------------- |
| `GET`  | `/api/v2/olly/views/artifacts/{artifact_id}` | List views for an artifact |
| `GET`  | `/api/v2/olly/views/{artifact_view_id}`      | Get a specific view by ID  |

## Artifact types

| Type                       | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `coralogix_logs`           | DataPrime log query results                      |
| `coralogix_spans`          | DataPrime span and trace query results           |
| `coralogix_metrics`        | PromQL metrics query results                     |
| `kubernetes_query_results` | Kubernetes resource query results                |
| `alert_watch_data`         | Alert trigger data with associated query results |
| `github_file_content`      | GitHub file content                              |

## Error handling

The API uses standard HTTP status codes. Error responses use this format:

```json
{
  "detail": "Human-readable error message"
}
```

| Status | Meaning                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------- |
| `400`  | Bad request (for example, empty content, invalid parameters)                                    |
| `403`  | Forbidden (Olly not enabled for the team, quota exceeded, team API key with no paid team quota) |
| `404`  | Resource not found                                                                              |
| `422`  | Validation error (invalid request body)                                                         |
| `425`  | Too early (for example, stopping an interaction that has not started)                           |

## Request body: create interaction

The `POST /api/v2/olly/v2/chats/{chat_id}/interactions/` endpoint accepts:

| Field              | Type           | Default     | Description                                                                                                                                                                                                       |
| ------------------ | -------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`          | `list[object]` | required    | List of content blocks. Each block has `type` and content fields.                                                                                                                                                 |
| `interaction_mode` | `string`       | `"skill"`   | The mode Olly uses for this interaction. Use `"skill"` for new integrations; `"focus"` and `"fast"` are accepted for backwards compatibility and route to `"skill"`. See [Interaction modes](#interaction-modes). |
| `model_choice`     | `string`       | `"gpt-5.4"` | AI model to use. See [Models](#models) for the available IDs.                                                                                                                                                     |
| `should_block`     | `boolean`      | `false`     | If `true`, wait for the agent to finish and return responses inline.                                                                                                                                              |
| `timeout_seconds`  | `integer`      | `900`       | Maximum seconds to wait. Only applies when `should_block=true`. Range: 1–3600.                                                                                                                                    |
| `user_file_ids`    | `list[UUID]`   | `[]`        | File IDs returned from the [file upload flow](#attach-files-to-a-message).                                                                                                                                        |
| `load_skill_ids`   | `list[UUID]`   | `[]`        | Skill IDs (personal or team) to pre-load before the Skills Agent's first turn. Up to 10 IDs. Requires `interaction_mode == "skill"`.                                                                              |

### Content block format

```json
{"type": "input_text", "text": "Your message here"}
```

### Response format: get chat

By default, `GET /api/v2/olly/v2/chats/{chat_id}` returns structured messages (`response_format=content_blocks`). Pass `response_format=events` to receive streaming events instead.

## Learn more

- [Olly chat](https://coralogix.com/docs/user-guides/olly/olly-chat/index.md)
- [Model selection](https://coralogix.com/docs/user-guides/olly/model-selection/index.md)
- [Olly pricing](https://coralogix.com/docs/user-guides/olly/pricing/index.md)
- [Data processing, privacy, and compliance](https://coralogix.com/docs/user-guides/olly/data-privacy/index.md)