Skip to main content
Theme
Home
Open in ChatGPTOpen in Claude

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 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​

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 (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 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​

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

Endpoint groupBase pathPersonal key (cxup_)Team key (cxtp_)
Chats and interactions/api/v2/olly/v2/chats/YesYes
Artifacts/api/v2/olly/artifacts/YesYes
Scheduled tasks/api/v2/olly/scheduled-tasks/YesNo
Data sources/api/v2/olly/data-sources/YesNo
User rules/api/v2/olly/user-rules/YesNo
Personal skills/api/v2/olly/skills/personalYesNo
Team rules/api/v2/olly/team-rules/Yes (with permission)Yes (with permission)
Team skills/api/v2/olly/skills/teamYes (with permission)Yes (with permission)
Feedback/api/v2/olly/feedback/YesYes

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:

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:

Callerentity_id value
Personal API keyThe user's ID.
Team API keyteam_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_typeWho can access
private (default)Only the owning entity_id.
specific_entitiesOnly the entity IDs listed in shared_entity_ids.
entire_organizationAny 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​

ConceptDescription
ChatA conversation session. Create one before sending messages.
InteractionA single user message and the AI response within a chat. Each message you send creates one interaction.
ArtifactA structured data object — logs, spans, or metrics — the agent produces during an interaction.
RuleA 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.
SkillA 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 sourceA 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.
FeedbackA 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)​

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 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, 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 for the in-product display names and recommended defaults.

Interaction status lifecycle​

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.

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 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​

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

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 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​

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​

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.

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​

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.
  • Only one data source per interaction.

See Data sources in the Endpoint reference for the full set of operations.

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 for the in-product UX.

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​

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 in the Endpoint reference for the full set of GET, PUT, and DELETE operations.

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 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 in the Endpoint reference for GET, PUT, and DELETE operations.

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

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​

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 in the Endpoint reference for PUT and DELETE operations.

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 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 in the Endpoint reference for the full set of GET, PUT, and DELETE operations.

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​

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​

Example request:

DELETE /api/v2/olly/feedback/
{
  "interaction_id": "e5f6g7h8-..."
}

Returns 200 OK with no body.

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 for the in-product UX.

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​

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​

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

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 in the Endpoint reference for the full list of operations.

Endpoint reference​

Chats​

MethodPathDescription
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}/titleGet a chat's title
PATCH/api/v2/olly/v2/chats/{chat_id}/titleRename 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}/sharedSet chat privacy and sharing options
POST/api/v2/olly/v2/chats/{chat_id}/stopStop an ongoing response generation

Interactions​

MethodPathDescription
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​

MethodPathDescription
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​

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

MethodPathDescription
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}/repositoriesList repositories the Olly app can access in the connected org
GET/api/v2/olly/data-sources/github/{data_source_id}/repositories/searchSearch repositories by name (required query parameter)

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 for the in-product UX.

MethodPathDescription
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}/scheduleReplace 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-runsList 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-runTrigger an on-demand run. Returns 204 No Content. Requires AI consent.

User rules​

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

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

MethodPathDescription
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​

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

MethodPathDescription
GET/api/v2/olly/skills/personalList personal skills owned by the caller
POST/api/v2/olly/skills/personalCreate 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​

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.

MethodPathDescription
GET/api/v2/olly/skills/teamList all team skills
POST/api/v2/olly/skills/teamCreate 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​

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

MethodPathDescription
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​

TypeDescription
coralogix_logsDataPrime log query results
coralogix_spansDataPrime span and trace query results
coralogix_metricsPromQL metrics query results
kubernetes_query_resultsKubernetes resource query results
alert_watch_dataAlert trigger data with associated query results
github_file_contentGitHub file content

Error handling​

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

{
  "detail": "Human-readable error message"
}
StatusMeaning
400Bad request (for example, empty content, invalid parameters)
403Forbidden (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)
404Resource not found
422Validation error (invalid request body)
425Too 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:

FieldTypeDefaultDescription
contentlist[object]requiredList of content blocks. Each block has type and content fields.
interaction_modestring—Deprecated and ignored. Olly always runs in Pro mode. The field is still accepted for backward compatibility with older clients. See Interaction mode (deprecated).
model_choicestring"gpt-5.4"AI model to use. See Models for the available IDs.
should_blockbooleanfalseIf true, wait for the agent to finish and return responses inline.
timeout_secondsinteger900Maximum seconds to wait. Only applies when should_block=true. Range: 1–3600.
load_skill_idslist[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.
data_sourceslist[object][]A GitHub data source for code-aware analysis. At most one entry. Each entry takes data_source_id (UUID from GET /data-sources/), type: "github", and repositories (a one-item list with the short repository name). See Use a data source in a chat.

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​

Last updated on
Need help? Contact Support.
What's new? Find out here.
LLM? Read llms.txt.
Domain selector
Choose region/domain
On this page
Was this page helpful?