API Reference

API Resources

Conversations

Conversations API

Manage conversations and messages between users and agents.

Conversation Management

List Conversations

GET /orgs/{organizationId}/conversations

Query Parameters:

agentId (optional): Filter by agent
q (optional): Search query string
limit (optional): Results per page (default: 20)
cursor (optional): Pagination offset
orderBy (optional): Sort field (default: last_message_created_at)
all (optional): Set to "true" to list all conversations (requires Admin/Owner role)

ℹ️

By default, this endpoint returns only conversations the user has access to. Admins and Owners can use all=true to list all conversations in the organization.

Response:

{
  "items": [
    {
      "conversationId": "conv-123",
      "organizationId": "org-456",
      "agentId": "agent-789",
      "title": "Customer Support Request",
      "creatorUserId": "user-101",
      "lastMessageCreatedAt": "2024-01-01T12:00:00Z",
      "createdAt": "2024-01-01T11:00:00Z",
      "updatedAt": "2024-01-01T12:00:00Z"
    }
  ],
  "totalRows": 1,
  "offset": 0
}

Create Conversation / Send Message

POST /orgs/{organizationId}/conversations

This endpoint serves two purposes:

Create a new conversation (without conversationId)
Send a message to an existing conversation (with conversationId)

Request Body:

{
  "agentId": "agent-456",
  "conversationId": "conv-123",
  "title": "Support Request",
  "message": "Hello, I need help",
  "assistantMessage": "I'll help you with that",
  "frontendTools": [],
  "requestId": "unique-request-id",
  "callbackUrl": "https://example.com/callback",
  "isBrowserTask": false
}

Required Fields:

agentId: ID of the agent to use

Optional Fields:

conversationId: If provided, loads existing conversation; if omitted, creates new one
title: Custom title for new conversations (auto-generated if omitted)
message: User message to send (if omitted, just creates/loads conversation without sending message)
assistantMessage: Pre-fill assistant message
frontendTools: Array of frontend tool configurations
requestId: Unique ID for tracking (auto-generated if omitted)
callbackUrl: URL to receive callback when agent completes
isBrowserTask: Flag for browser automation tasks

Response:

{
  "conversationId": "conv-123",
  "organizationId": "org-456",
  "agentId": "agent-789",
  "title": "Support Request",
  "creatorUserId": "user-101",
  "requestId": "unique-request-id",
  "createdAt": "2024-01-01T11:00:00Z",
  "updatedAt": "2024-01-01T11:00:00Z"
}

ℹ️

When message is provided, the message is queued for processing and the agent’s response is delivered via WebSocket. The response returns immediately with the conversation details and requestId for tracking.

Get Conversation

GET /orgs/{organizationId}/conversations/{id}

Returns conversation details including all messages.

Response:

{
  "conversationId": "conv-123",
  "organizationId": "org-456",
  "agentId": "agent-789",
  "title": "Support Request",
  "creatorUserId": "user-101",
  "createdAt": "2024-01-01T11:00:00Z",
  "updatedAt": "2024-01-01T12:00:00Z",
  "messages": [
    {
      "messageId": "msg-1",
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Hello, I need help"
        }
      ],
      "createdAt": "2024-01-01T11:00:00Z"
    },
    {
      "messageId": "msg-2",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "I'll help you with that"
        }
      ],
      "createdAt": "2024-01-01T11:01:00Z"
    }
  ]
}

Update Conversation

PUT /orgs/{organizationId}/conversations/{id}

Required Field:

title: New conversation title

Request Body:

{
  "title": "Updated conversation title"
}

Response: Returns updated conversation view

Delete Conversation

DELETE /orgs/{organizationId}/conversations/{id}

Permanently deletes the conversation and all its messages.

Response:

{
  "organizationId": "org-456",
  "conversationId": "conv-123"
}

Task Plans

Task plans represent multi-step workflows executed by agents. They track progress through complex tasks that require multiple steps.

List Task Plans

GET /orgs/{organizationId}/conversations/{conversationId}/task-plans

Returns all active task plans (both general and browser types) for the conversation.

Response:

[
  {
    "planId": "plan-123",
    "conversationId": "conv-456",
    "organizationId": "org-789",
    "type": "general",
    "status": "in_progress",
    "steps": [
      {
        "stepId": "step-1",
        "description": "Analyze data",
        "status": "completed"
      },
      {
        "stepId": "step-2",
        "description": "Generate report",
        "status": "in_progress"
      }
    ],
    "createdAt": "2024-01-01T11:00:00Z",
    "updatedAt": "2024-01-01T11:05:00Z"
  }
]

Get Task Plan

GET /orgs/{organizationId}/conversations/{conversationId}/task-plans/{planId}

Returns detailed information about a specific task plan.

Cancel Task Plan

POST /orgs/{organizationId}/conversations/{conversationId}/task-plans/{planId}/cancel

Cancels a running task plan. Execution will stop after the current task completes.

Response:

{
  "success": true,
  "message": "Task plan cancellation requested. Execution will stop after current task completes.",
  "planId": "plan-123"
}

⚠️

Cancellation is not immediate - the currently executing task will complete before the plan stops.

Data Analysis

Create and manage data analysis sessions within conversations.

Create Analysis

POST /orgs/{organizationId}/conversations/{conversationId}/analysis

Request Body:

{
  "title": "Sales Data Analysis",
  "description": "Q3 2024 sales analysis"
}

List Analyses

GET /orgs/{organizationId}/conversations/{conversationId}/analysis

Get Analysis

GET /orgs/{organizationId}/conversations/{conversationId}/analysis/{analysisId}

Update Analysis

PUT /orgs/{organizationId}/conversations/{conversationId}/analysis/{analysisId}

Delete Analysis

DELETE /orgs/{organizationId}/conversations/{conversationId}/analysis/{analysisId}

Browser Sessions

Manage browser automation sessions within conversations.

Create Browser Session

POST /orgs/{organizationId}/conversations/{conversationId}/browser-sessions

List Browser Sessions

GET /orgs/{organizationId}/conversations/{conversationId}/browser-sessions

Stop Browser Session

POST /orgs/{organizationId}/conversations/{conversationId}/browser-sessions/{sessionId}/stop

WebSocket Events

Agent responses and real-time updates are delivered via WebSocket connection. Connect to:

wss://ws.intellia.com.au

Authentication: Include JWT token in connection headers

Message Types:

conversation - Message updates (content deltas, tool calls)
tool-update - Tool execution status
task-plan - Task plan progress updates

See WebSocket Documentation for details.

Best Practices

Use Request IDs - Include unique requestId for message tracking and idempotency
WebSocket Connection - Maintain persistent WebSocket for real-time responses
Conversation Reuse - Continue existing conversations rather than creating new ones unnecessarily
Pagination - Use cursor-based pagination for large conversation lists
Title Updates - Intellia auto-generates titles, but you can override them as needed

Agents Knowledge Bases