Olly REST API

Use the Olly REST API to make Olly 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 two flows: chats and interactions (creating chats, sending messages, polling for responses) and artifacts (retrieving the structured data Olly produces during an interaction).

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.

Authentication

Every request requires an API key, 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 using the domain selector at the top of the page.

Example:

curl -H "Authorization: Bearer <cx_api_key>" \
  https://api./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

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

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.

See Olly chat 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 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:

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)

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

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.

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

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

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

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

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.

Endpoint reference

Chats

Interactions

Artifacts

Artifact types

Error handling

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

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

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.
model_choice	string	"gpt-5.4"	AI model to use. See 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.

Content block format

{"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
• Model selection
• Olly pricing
• Data processing, privacy, and compliance