Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fdeveloper-portal%2Fapis%2Folly.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fdeveloper-portal%2Fapis%2Folly.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Olly REST API

Use the **Olly REST API** to make [Olly](https://coralogix.com/docs/docs/user-guides/olly/.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 Olly generates — all using the same models, skills, and permissions as the in-product chat.

The API surface covers **chats and interactions** (creating chats, sending messages, polling for responses), **artifacts** (retrieving the structured data Olly produces during an interaction), **scheduled tasks** (prompts that run automatically on a one-off or recurring schedule), the GitHub **data sources** users connect for code-aware investigations, and the configuration that shapes Olly's behavior — **user and team rules**, **personal and team skills**, and **interaction feedback**.

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.
* Syncing rules and skills from your own knowledge base, feature flag system, or version control — so the instructions that shape Olly stay aligned with the code and runbooks they describe.

## What you need[​](#what-you-need "Direct link to 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/docs/user-guides/olly/enable/.md).

## Authentication[​](#authentication "Direct link to Authentication")

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

* **Personal API key** (prefix `cxup_`): tied to a single user. Token consumption is deducted from the user's quota.
* **Team API key** (prefix `cxtp_`): 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/docs/user-guides/account-management/account-settings/coralogix-domain/.md) using the domain selector at the top of the page.

**Example:**

```
curl -H "Authorization: Bearer <cx_api_key>" \

  https://api.eu2.coralogix.com/api/v2/olly/v2/chats/
```

### Key type support per endpoint group[​](#key-type-support-per-endpoint-group "Direct link to Key type support per endpoint group")

Endpoint groups have different ownership models, so they accept different key types:

| Endpoint group         | Base path                       | Personal key (`cxup_`) | Team key (`cxtp_`)    |
| ---------------------- | ------------------------------- | ---------------------- | --------------------- |
| Chats and interactions | `/api/v2/olly/v2/chats/`        | Yes                    | Yes                   |
| Artifacts              | `/api/v2/olly/artifacts/`       | Yes                    | Yes                   |
| Scheduled tasks        | `/api/v2/olly/scheduled-tasks/` | Yes                    | No                    |
| Data sources           | `/api/v2/olly/data-sources/`    | Yes                    | No                    |
| User rules             | `/api/v2/olly/user-rules/`      | Yes                    | No                    |
| Personal skills        | `/api/v2/olly/skills/personal`  | Yes                    | No                    |
| Team rules             | `/api/v2/olly/team-rules/`      | Yes (with permission)  | Yes (with permission) |
| Team skills            | `/api/v2/olly/skills/team`      | Yes (with permission)  | Yes (with permission) |
| Feedback               | `/api/v2/olly/feedback/`        | Yes                    | Yes                   |

Scheduled tasks, data sources, user rules, and personal skills are user-scoped — they read and write data tied to a single user identity. A team key carries no user identity, so calls to these endpoints with a team key return `403 Forbidden`. Use a personal API key.

Team rules and team skills accept both key types, but the caller's identity needs the matching permission in the **AI** permission group:

* [`OLLY-TEAM-RULES:READ`](https://coralogix.com/docs/docs/user-guides/aaa/access-control/permissions/permissions-list/.md) to read team rules, [`OLLY-TEAM-RULES:MANAGE`](https://coralogix.com/docs/docs/user-guides/aaa/access-control/permissions/permissions-list/.md) to create, update, or delete them.
* [`OLLY-TEAM-SKILLS:VIEW`](https://coralogix.com/docs/docs/user-guides/aaa/access-control/permissions/permissions-list/.md) to read team skills, [`OLLY-TEAM-SKILLS:MANAGE`](https://coralogix.com/docs/docs/user-guides/aaa/access-control/permissions/permissions-list/.md) to create, update, or delete them.

### Entity identity[​](#entity-identity "Direct link to 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-control "Direct link to 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[​](#core-concepts "Direct link to 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.                                                                                                                                                          |
| **Rule**        | A custom instruction that shapes how Olly behaves. **User rules** apply for one user; **team rules** apply for everyone in the team and are admin-managed.                                                                                              |
| **Skill**       | A reusable, named instruction set Olly can pre-load into an interaction by passing the IDs in `load_skill_ids` on the create-interaction request. **Personal skills** belong to one user; **team skills** are shared and admin-managed.                 |
| **Data source** | A GitHub connection a user wires up in the Olly UI so Olly can analyze code during an investigation. Currently one connection per user, type `github`. The API exposes read and manage operations — creation happens through the in-product OAuth flow. |
| **Feedback**    | A thumbs-up or thumbs-down recorded on an interaction. Used to improve future responses.                                                                                                                                                                |

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, managing rules and skills, and submitting feedback.

### Interaction mode (deprecated)[​](#interaction-mode-deprecated "Direct link to Interaction mode (deprecated)")

The `interaction_mode` field on the create-interaction request is **deprecated and ignored**. Every API interaction runs in Olly's **Pro** mode — the same single mode used in the Coralogix UI. Pro applies a curated set of specialized skills to each request, extensible with your own custom skills.

The field is still accepted for backward compatibility with older clients. The values `skill`, `focus`, and `fast` all route to Pro. Drop the field from new integrations.

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

### Models[​](#models "Direct link to 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`, `claude-opus-4-8`, `claude-sonnet-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/docs/user-guides/olly/model-selection/.md) for the in-product display names and recommended defaults.

### Interaction status lifecycle[​](#interaction-status-lifecycle "Direct link to Interaction status lifecycle")

<!-- -->

## Send a message and wait for the response[​](#send-a-message-and-wait-for-the-response "Direct link to 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[​](#step-1-create-a-chat "Direct link to Step 1: Create a chat")

**Example request:**

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

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

```
{

  "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)[​](#step-2-send-a-message-wait-inline "Direct link to Step 2: Send a message (wait inline)")

**Example request:**

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

```
{

  "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):

```
{

  "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[​](#poll-for-response "Direct link to 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[​](#step-1-create-a-chat-1 "Direct link to Step 1: Create a chat")

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

### Step 2: Send a message (non-blocking)[​](#step-2-send-a-message-non-blocking "Direct link to Step 2: Send a message (non-blocking)")

**Example request:**

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

```
{

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

}
```

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

```
{

  "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[​](#step-3-poll-for-completion "Direct link to Step 3: Poll for completion")

**Example request:**

```
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`):

```
{

  "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..."}]

    }

  ]

}
```

## Manage artifacts[​](#manage-artifacts "Direct link to Manage artifacts")

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

### List artifacts for a chat[​](#list-artifacts-for-a-chat "Direct link to List artifacts for a chat")

**Example request:**

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

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

```
[

  {

    "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[​](#get-an-artifact-with-download-url "Direct link to Get an artifact with download URL")

**Example request:**

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

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

```
{

  "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.

## Manage data sources[​](#manage-data-sources "Direct link to Manage data sources")

Data sources are the GitHub connections that let Olly analyze code during an investigation. The endpoint group is personal-key only — a team key receives `403 Forbidden`. See [GitHub](https://coralogix.com/docs/docs/user-guides/olly/github/.md) for the in-product UX.

The API is read and manage only. You cannot create a connection through the API — users connect GitHub through the OAuth flow in the Olly UI first, then this API lists, updates, and deletes what they connected. Each user can connect one GitHub data source today.

The `config` object returned by the API exposes the GitHub organization name and the expiration status. OAuth secrets (refresh tokens, integration IDs) are never returned.

### List data sources[​](#list-data-sources "Direct link to List data sources")

**Example request:**

```
GET /api/v2/olly/data-sources/
```

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

```
[

  {

    "id": "9a3f2b1c-...",

    "team_id": "team-abc",

    "name": "acme-corp GitHub",

    "description": "Engineering org",

    "type": "github",

    "config": {

      "github_organization_name": "acme-corp",

      "is_data_source_expired": false,

      "expiration_reason": null

    },

    "created_at": "2026-06-20T10:30:00Z",

    "updated_at": "2026-06-20T10:30:00Z",

    "is_ingestion_completed": true

  }

]
```

An empty list `[]` is the normal response for a user who has not connected GitHub yet — point them to the [in-product flow](https://coralogix.com/docs/docs/user-guides/olly/github/.md#connect-github-as-an-individual-user). When `is_data_source_expired` is `true`, the user must re-authenticate in the UI; `expiration_reason` is `oauth_expired` or `integration_deleted`.

### Get a data source[​](#get-a-data-source "Direct link to Get a data source")

**Example request:**

```
GET /api/v2/olly/data-sources/{data_source_id}
```

Returns the same `DataSourceRead` shape as the list endpoint.

### Update a data source[​](#update-a-data-source "Direct link to Update a data source")

Update the display `name`, the `description`, or both. The GitHub connection itself (organization, repositories) is managed in the Olly UI — there is no API to rebind a data source to a different org.

**Example request:**

```
PUT /api/v2/olly/data-sources/{data_source_id}
```

```
{

  "name": "acme-corp prod GitHub",

  "description": "Production repos only"

}
```

**Example response** (`200 OK`): the updated `DataSourceRead`.

### Delete a data source[​](#delete-a-data-source "Direct link to Delete a data source")

**Example request:**

```
DELETE /api/v2/olly/data-sources/{data_source_id}
```

Returns `204 No Content` on success. Deleting a data source removes the connection record only — the underlying GitHub app installation in your GitHub organization is unaffected. To revoke the Olly app in GitHub, use the in-product **Disconnect GitHub** flow.

### List repositories in a connected GitHub org[​](#list-repositories-in-a-connected-github-org "Direct link to List repositories in a connected GitHub org")

After a user connects GitHub, fetch the repositories the Olly app has access to in their organization. Use this list to populate a picker before sending a chat message with code context.

**Example request:**

```
GET /api/v2/olly/data-sources/github/{data_source_id}/repositories
```

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

```
[

  {

    "id": 123456789,

    "name": "checkout-service",

    "full_name": "acme-corp/checkout-service",

    "private": true,

    "description": "Payments checkout API"

  }

]
```

The `name` field is the short repository name — pass it as-is in the `repositories` list when sending a chat message. See [Use a data source in a chat](#use-a-data-source-in-a-chat).

### Search repositories[​](#search-repositories "Direct link to Search repositories")

**Example request:**

```
GET /api/v2/olly/data-sources/github/{data_source_id}/repositories/search?query=checkout
```

`query` is required, minimum 1 character. Returns the same `GithubRepositoryPartial` shape as the list endpoint, filtered by name match.

### Use a data source in a chat[​](#use-a-data-source-in-a-chat "Direct link to Use a data source in a chat")

Pass the data source ID and one repository name on the create-interaction request to scope the chat to a specific repository.

**Example request:**

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

```
{

  "content": [{"type": "input_text", "text": "Where does this log line originate in the codebase?"}],

  "data_sources": [

    {

      "data_source_id": "9a3f2b1c-...",

      "type": "github",

      "repositories": ["checkout-service"]

    }

  ],

  "should_block": true

}
```

Rules:

* The `data_source_id` is the `id` returned by `GET /api/v2/olly/data-sources/`.
* `repositories` accepts exactly one entry, the short repository name (for example, `"checkout-service"` — not `"acme-corp/checkout-service"`). Get it from the [repositories list endpoint](#list-repositories-in-a-connected-github-org).
* Only one data source per interaction.

See [Data sources](#data-sources) in the Endpoint reference for the full set of operations.

## Manage user rules[​](#manage-user-rules "Direct link to Manage user rules")

User rules are custom instructions Olly applies to every chat for the calling user. The endpoint is personal-key only — a team key receives `403 Forbidden`. See [Rules](https://coralogix.com/docs/docs/user-guides/olly/rules/.md) for the in-product UX.

### Create a user rule[​](#create-a-user-rule "Direct link to Create a user rule")

**Example request:**

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

```
{

  "rule": "When investigating incidents, prioritize production environments over staging."

}
```

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

```
{

  "id": "4e3d2c1b-...",

  "rule": "When investigating incidents, prioritize production environments over staging.",

  "enabled": true,

  "created_at": "2026-06-22T10:30:00Z"

}
```

### List user rules[​](#list-user-rules "Direct link to List user rules")

**Example request:**

```
GET /api/v2/olly/user-rules/
```

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

```
[

  {

    "id": "4e3d2c1b-...",

    "rule": "When investigating incidents, prioritize production environments over staging.",

    "enabled": true,

    "created_at": "2026-06-22T10:30:00Z"

  }

]
```

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

## Manage team rules[​](#manage-team-rules "Direct link to Manage team rules")

Team rules are instructions that apply to every team member. The endpoint shape mirrors user rules; the difference is scope and permissions — reading team rules requires `OLLY-TEAM-RULES:READ`, and creating, updating, or deleting one requires `OLLY-TEAM-RULES:MANAGE`. See [Rules](https://coralogix.com/docs/docs/user-guides/olly/rules/.md#permissions-for-team-rules) for the in-product UX and the permission keys.

**Example request:** create a team rule

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

```
{

  "rule": "Always check the most recent deploy events before correlating an alert with code changes."

}
```

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

```
{

  "id": "7b6a5c4d-...",

  "rule": "Always check the most recent deploy events before correlating an alert with code changes.",

  "enabled": true,

  "created_at": "2026-06-22T10:30:00Z"

}
```

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

## Manage personal skills[​](#manage-personal-skills "Direct link to Manage personal skills")

Personal skills are reusable, named instruction sets you can pre-load into an interaction by passing their IDs in `load_skill_ids` on the create-interaction request. The endpoint is personal-key only — a team key receives `403 Forbidden`. See [Skills](https://coralogix.com/docs/docs/user-guides/olly/skills/.md) for the in-product UX, naming rules, validation, and limits.

### Create a personal skill[​](#create-a-personal-skill "Direct link to Create a personal skill")

**Example request:**

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

```
{

  "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`):

```
{

  "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-06-22T10:30:00Z",

  "scope": "personal"

}
```

Constraints: `name` ≤ 64 characters, `description` ≤ 1200 characters, `content` ≤ 40960 characters.

### List personal skills[​](#list-personal-skills "Direct link to List personal skills")

**Example request:**

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

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

```
[

  {

    "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-06-22T10:30:00Z",

    "scope": "personal"

  }

]
```

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

## Manage team skills[​](#manage-team-skills "Direct link to Manage team skills")

Team skills are reusable instruction sets that apply for every team member's chats. The endpoint shape mirrors personal skills; the difference is scope and permissions — reading team skills requires `OLLY-TEAM-SKILLS:VIEW`, and creating, updating, or deleting one requires `OLLY-TEAM-SKILLS:MANAGE`. See [Skills](https://coralogix.com/docs/docs/user-guides/olly/skills/.md#permissions-for-team-skills) for the in-product UX and the permission keys.

**Example request:** create a team skill

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

```
{

  "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`):

```
{

  "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-06-22T10:30:00Z",

  "scope": "team"

}
```

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

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

## Submit feedback[​](#submit-feedback "Direct link to Submit feedback")

Record or remove a thumbs-up or thumbs-down on a specific interaction. Both key types work — there are no permission gates.

### Set feedback[​](#set-feedback "Direct link to Set feedback")

**Example request:**

```
POST /api/v2/olly/feedback/
```

```
{

  "interaction_id": "e5f6g7h8-...",

  "feedback": "positive",

  "description": "Correct root cause on the first turn."

}
```

`feedback` accepts `"positive"` or `"negative"`. `description` is optional. The endpoint returns `200 OK` with no body.

### Remove feedback[​](#remove-feedback "Direct link to Remove feedback")

**Example request:**

```
DELETE /api/v2/olly/feedback/
```

```
{

  "interaction_id": "e5f6g7h8-..."

}
```

Returns `200 OK` with no body.

## Manage scheduled tasks[​](#manage-scheduled-tasks "Direct link to Manage scheduled tasks")

Schedule a prompt to run automatically — once at a future time, or recurring on a fixed interval — without keeping a user in the loop. Each run produces its own chat that you can retrieve with the standard chat endpoints. Scheduled tasks are scoped to the calling entity: a personal API key sees and manages only that user's tasks; team API keys aren't supported for this surface. See [Scheduled tasks](https://coralogix.com/docs/docs/user-guides/olly/scheduled-tasks/.md) for the in-product UX.

### Create a recurring scheduled task[​](#create-a-recurring-scheduled-task "Direct link to Create a recurring scheduled task")

**Example request:**

```
POST /api/v2/olly/scheduled-tasks/
```

```
{

  "title": "Daily error summary",

  "prompt": "Summarize the top error categories in the payment service over the last 24 hours and graph them.",

  "model_choice": "gpt-5.4",

  "start_at": "2026-06-08T09:00:00Z",

  "interval_seconds": 86400,

  "enabled": true

}
```

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

```
{

  "id": "f1e2d3c4-...",

  "team_id": "team_abc-123",

  "entity_id": "user_abc-123",

  "title": "Daily error summary",

  "prompt": "Summarize the top error categories in the payment service over the last 24 hours and graph them.",

  "model_choice": "gpt-5.4",

  "start_at": "2026-06-08T09:00:00Z",

  "interval_seconds": 86400,

  "next_run_at": "2026-06-08T09:00:00Z",

  "last_run_at": null,

  "enabled": true,

  "scheduled_task_type": "recurring",

  "created_at": "2026-06-07T10:30:00Z",

  "updated_at": "2026-06-07T10:30:00Z"

}
```

Constraints: `interval_seconds` is `3600`–`604800` (1 hour to 1 week). `start_at` must be in the future and no later than 1 week from now. Omit `interval_seconds` to create a one-off task — the response's computed `scheduled_task_type` is then `"oneoff"` instead of `"recurring"`. Each entity can own at most **20** scheduled tasks; the endpoint returns `409 Conflict` once that quota is reached.

### Edit a scheduled task[​](#edit-a-scheduled-task "Direct link to Edit a scheduled task")

Editing a task uses two separate endpoints:

* `PATCH /api/v2/olly/scheduled-tasks/{task_id}` — update content (any of `title`, `prompt`, `model_choice`). At least one field is required.
* `PUT /api/v2/olly/scheduled-tasks/{task_id}/schedule` — replace the schedule. The request body always carries `start_at`, plus optional `interval_seconds` and `enabled`. If `start_at` is in the past, `interval_seconds` is required.

### List runs for a scheduled task[​](#list-runs-for-a-scheduled-task "Direct link to List runs for a scheduled task")

**Example request:**

```
GET /api/v2/olly/scheduled-tasks/{task_id}/scheduled-task-runs
```

**Example response** (`200 OK`, most recent first):

```
[

  {

    "id": "11111111-...",

    "scheduled_task_id": "f1e2d3c4-...",

    "team_id": "team_abc-123",

    "status": "succeeded",

    "chat_id": "c0c0c0c0-...",

    "interaction_id": "aaaaaaaa-...",

    "started_at": "2026-06-08T09:00:00Z",

    "finished_at": "2026-06-08T09:01:42Z",

    "error_reason": null

  }

]
```

`status` is one of `pending`, `running`, `succeeded`, or `failed`. When a run dispatched to the agent successfully, `chat_id` and `interaction_id` point to the resulting chat and interaction — retrieve them with the standard [chat](#endpoint-reference) and [interaction](#interactions) endpoints. When dispatch itself failed, `status` is `failed`, `chat_id` is `null`, and `error_reason` carries one of: `"quota_exceeded"` (the team's Olly quota ran out), `"ai_consent_denied"` (the team's **AI-Powered Capabilities** toggle was off when the run fired), or `"general_error"` (any other dispatch failure).

### Trigger an on-demand run[​](#trigger-an-on-demand-run "Direct link to Trigger an on-demand run")

Trigger a run outside the schedule — useful for testing a newly created task without waiting for the next scheduled time:

```
POST /api/v2/olly/scheduled-tasks/{task_id}/manual-run
```

Returns `204 No Content` and requires AI consent (the same **AI-Powered Capabilities** toggle covered in [What you need](#what-you-need)).

Chats produced by a scheduled task carry the originating task's ID in `metadata.scheduled_task_id`, letting you correlate chats back to the task that created them when you list or fetch chats.

See [Scheduled tasks](#scheduled-tasks) in the Endpoint reference for the full list of operations.

## Endpoint reference[​](#endpoint-reference "Direct link to Endpoint reference")

### Chats[​](#chats "Direct link to 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/{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[​](#interactions "Direct link to 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   |

### Artifacts[​](#artifacts "Direct link to 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    |

### Data sources[​](#data-sources "Direct link to Data sources")

GitHub connections users wire up in the Olly UI for code-aware investigations. Personal key only.

| Method   | Path                                                                    | Description                                                    |
| -------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
| `GET`    | `/api/v2/olly/data-sources/`                                            | List the caller's data sources                                 |
| `GET`    | `/api/v2/olly/data-sources/{data_source_id}`                            | Get a data source by ID                                        |
| `PUT`    | `/api/v2/olly/data-sources/{data_source_id}`                            | Update a data source's name or description                     |
| `DELETE` | `/api/v2/olly/data-sources/{data_source_id}`                            | Delete a data source (returns `204 No Content`)                |
| `GET`    | `/api/v2/olly/data-sources/github/{data_source_id}/repositories`        | List repositories the Olly app can access in the connected org |
| `GET`    | `/api/v2/olly/data-sources/github/{data_source_id}/repositories/search` | Search repositories by name (required `query` parameter)       |

### Scheduled tasks[​](#scheduled-tasks "Direct link to Scheduled tasks")

Schedule a prompt to run automatically on a one-off or recurring schedule. Tasks are scoped to the calling entity. Personal key only. See [Scheduled tasks](https://coralogix.com/docs/docs/user-guides/olly/scheduled-tasks/.md) for the in-product UX.

| Method   | Path                                                         | Description                                                                                                                                                                                                                                                                                     |
| -------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/api/v2/olly/scheduled-tasks/`                              | List scheduled tasks owned by the calling entity.                                                                                                                                                                                                                                               |
| `POST`   | `/api/v2/olly/scheduled-tasks/`                              | Create a scheduled task. Required body fields: `title`, `prompt`, `model_choice`, `start_at`. Optional: `interval_seconds` (3600–604800), `enabled` (default `true`). Returns `409 Conflict` if the entity already owns 20 tasks.                                                               |
| `GET`    | `/api/v2/olly/scheduled-tasks/{task_id}`                     | Get a single scheduled task. The response includes a computed `scheduled_task_type` field (`"oneoff"` or `"recurring"`).                                                                                                                                                                        |
| `PATCH`  | `/api/v2/olly/scheduled-tasks/{task_id}`                     | Update task content. Body may include any of `title`, `prompt`, `model_choice` — at least one is required.                                                                                                                                                                                      |
| `PUT`    | `/api/v2/olly/scheduled-tasks/{task_id}/schedule`            | Replace the task's schedule. Body: `start_at` (required), `interval_seconds` (optional), `enabled` (optional, default `true`). `interval_seconds` is required when `start_at` is in the past.                                                                                                   |
| `DELETE` | `/api/v2/olly/scheduled-tasks/{task_id}`                     | Delete a scheduled task. Past chats from its runs are kept.                                                                                                                                                                                                                                     |
| `GET`    | `/api/v2/olly/scheduled-tasks/{task_id}/scheduled-task-runs` | List runs for a task, most recent first. Each entry has `status` (`pending` \| `running` \| `succeeded` \| `failed`), `chat_id`, `interaction_id`, `started_at`, `finished_at`, and `error_reason` (`quota_exceeded` \| `ai_consent_denied` \| `general_error`, or `null` for non-failed runs). |
| `POST`   | `/api/v2/olly/scheduled-tasks/{task_id}/manual-run`          | Trigger an on-demand run. Returns `204 No Content`. Requires AI consent.                                                                                                                                                                                                                        |

### User rules[​](#user-rules "Direct link to User rules")

Custom instructions that shape how Olly behaves for the calling user. Personal key only.

| Method   | Path                                | Description                                  |
| -------- | ----------------------------------- | -------------------------------------------- |
| `GET`    | `/api/v2/olly/user-rules/`          | List all user rules for the caller           |
| `POST`   | `/api/v2/olly/user-rules/`          | Create a user rule                           |
| `GET`    | `/api/v2/olly/user-rules/{rule_id}` | Get a user rule by ID                        |
| `PUT`    | `/api/v2/olly/user-rules/{rule_id}` | Update a user rule's text or `enabled` field |
| `DELETE` | `/api/v2/olly/user-rules/{rule_id}` | Delete a user rule                           |

### Team rules[​](#team-rules "Direct link to Team rules")

Team-wide instructions that shape how Olly behaves for everyone in the team. Both key types work, provided the caller has the `OLLY-TEAM-RULES:READ` or `OLLY-TEAM-RULES:MANAGE` permission.

| Method   | Path                                | Description                                  |
| -------- | ----------------------------------- | -------------------------------------------- |
| `GET`    | `/api/v2/olly/team-rules/`          | List all team rules                          |
| `POST`   | `/api/v2/olly/team-rules/`          | Create a team rule                           |
| `GET`    | `/api/v2/olly/team-rules/{rule_id}` | Get a team rule by ID                        |
| `PUT`    | `/api/v2/olly/team-rules/{rule_id}` | Update a team rule's text or `enabled` field |
| `DELETE` | `/api/v2/olly/team-rules/{rule_id}` | Delete a team rule                           |

### Personal skills[​](#personal-skills "Direct link to Personal skills")

Reusable instructions Olly applies for the calling user. Personal key only.

| Method   | Path                                      | Description                              |
| -------- | ----------------------------------------- | ---------------------------------------- |
| `GET`    | `/api/v2/olly/skills/personal`            | List personal skills owned by the caller |
| `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                  |

### Team skills[​](#team-skills "Direct link to Team skills")

Reusable instructions Olly applies for everyone in the team. Both key types work, provided the caller has the `OLLY-TEAM-SKILLS:VIEW` or `OLLY-TEAM-SKILLS:MANAGE` permission.

| Method   | Path                                  | Description          |
| -------- | ------------------------------------- | -------------------- |
| `GET`    | `/api/v2/olly/skills/team`            | List all team skills |
| `POST`   | `/api/v2/olly/skills/team`            | Create a team skill  |
| `PUT`    | `/api/v2/olly/skills/team/{skill_id}` | Update a team skill  |
| `DELETE` | `/api/v2/olly/skills/team/{skill_id}` | Delete a team skill  |

### Feedback[​](#feedback "Direct link to Feedback")

Record or remove a thumbs-up / thumbs-down on a specific interaction. Both key types work.

| Method   | Path                     | Description                                               |
| -------- | ------------------------ | --------------------------------------------------------- |
| `POST`   | `/api/v2/olly/feedback/` | Set feedback (`positive` or `negative`) on an interaction |
| `DELETE` | `/api/v2/olly/feedback/` | Remove feedback from an interaction                       |

## Artifact types[​](#artifact-types "Direct link to 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[​](#error-handling "Direct link to Error handling")

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

```
{

  "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, team API key on a user-scoped endpoint, or missing team permission on a team-scoped endpoint) |
| `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[​](#request-body-create-interaction "Direct link to 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`       | —           | **Deprecated and ignored.** Olly always runs in Pro mode. The field is still accepted for backward compatibility with older clients. See [Interaction mode (deprecated)](#interaction-mode-deprecated).                                                                                                              |
| `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.                                                                                                                                                                                                                                       |
| `load_skill_ids`   | `list[string]` | `[]`        | A list of personal or team skill IDs (UUID strings) to pre-load before Olly's first turn. Manage skills with the [skills endpoints](#manage-personal-skills).                                                                                                                                                        |
| `data_sources`     | `list[object]` | `[]`        | A GitHub data source for code-aware analysis. At most one entry. Each entry takes `data_source_id` (UUID from [`GET /data-sources/`](#manage-data-sources)), `type: "github"`, and `repositories` (a one-item list with the short repository name). See [Use a data source in a chat](#use-a-data-source-in-a-chat). |

### Content block format[​](#content-block-format "Direct link to Content block format")

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

### Response format: get chat[​](#response-format-get-chat "Direct link to 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[​](#learn-more "Direct link to Learn more")

* [Olly chat](https://coralogix.com/docs/docs/user-guides/olly/olly-chat/.md)
* [Model selection](https://coralogix.com/docs/docs/user-guides/olly/model-selection/.md)
* [AI units pricing](https://coralogix.com/docs/docs/user-guides/account-management/payment-and-billing/ai-units-pricing/.md)
* [Data processing, privacy, and compliance](https://coralogix.com/docs/docs/user-guides/olly/data-privacy/.md)