Olly API

Use the Olly 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, 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.

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

Interaction modes

Every API interaction runs in skill mode — Pro mode in the in-product Olly chat. This is the default for interaction_mode and the mode the API is built around: Olly applies a curated set of specialized skills to each request, extensible with your own custom skills.

For background on Pro mode, see Olly modes.

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

Get started

This section 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.

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

Polling flow

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 in the wait-for-the-response flow.

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

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:

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

Example response (200 OK):

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

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

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

Example response (201 Created):

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

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:

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

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

To retrieve a previously uploaded file later, use:

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.

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:

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.

Get views (charts and tables) for an artifact

Example request:

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

Example response (200 OK):

[
  {
    "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 for the in-product UX, validation, and limits.

Example request: create a rule

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

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

Example response (201 Created):

{
  "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 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 for the in-product UX and the permission keys.

Example request: create a team rule

POST /api/v2/olly/team-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-05-27T10:30:00Z"
}

See 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 for the in-product UX, naming rules, validation, and limits.

Example request: create a skill

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-05-27T10:30:00Z",
  "entity_id": "user_abc-123"
}

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

Example request: list personal skills

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-05-27T10:30:00Z",
    "entity_id": "user_abc-123"
  }
]

See Skills in the Endpoint reference for PUT and DELETE operations.

Endpoint reference

Chats

Interactions

User files

User rules

User rules are personal instructions Olly applies to every chat. See Rules 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 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. See Skills 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

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

Artifacts

Artifact views

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 but deprecated. 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.
user_file_ids	list[UUID]	[]	File IDs returned from the file upload flow.
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

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