# Chatbase

> Manage Chatbase agents and knowledge sources, chat with agents, and search and export conversations.

App · 23 actions. Web page: https://docs.lodol.com/docs/integrations/chatbase

## Actions

### Chat with an agent

Send a message to an agent and receive a response. Supports streaming responses when stream: true is set in the request body.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Message (`message`, text, required): The user message to send to the agent. Omit to continue the conversation after submitting a tool result.
- Conversation ID (`conversation_id`, text): Optional conversation ID to continue an existing conversation. If omitted, a new conversation will be started.
- API user ID (`api_user_id`, text): Optional user ID to associate with a new conversation. Only applied when creating a new conversation (no conversationId). Once set, a conversation's userId is immutable , this field is ignored for existing conversations. Must contain only URL-safe characters (letters, digits, hyphens, underscores, dots).

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": {
      "id": "example",
      "metadata": {
        "conversationId": "example",
        "finishReason": "stop",
        "usage": {
          "credits": 1
        },
        "userId": "example",
        "userMessageId": "example"
      },
      "parts": [],
      "role": "assistant"
    }
  }
}
```

### Clone agent

Create a full deep-clone of an agent, including all its sources (excluding Notion). Returns the new agent ID.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "id": "example",
    "pendingSteps": []
  }
}
```

### Create agent

Create a new agent. If url is provided, a link source is created from that URL and training is queued automatically.

**Inputs**

- Name (`name`, text, required): Agent name
- URL (`url`, text): Homepage URL of the product. The agent is pre-configured to answer questions about this website.
- Instructions (`instructions`, text): System prompt / instructions for the agent (max 30,000 characters)
- Model (`model`, text): AI model to use. One of: `gpt-oss-120b`, `gpt-oss-20b`, `gpt-5.2`, `gpt-5.5`, `gpt-5.6-terra`, `gpt-6.1-sol`, `gpt-6-luna`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5`, and 18 more.
- Temp (`temp`, number): Model temperature (0 to 1). From 0.0 to 1.0.
- Visibility (`visibility`, text): Agent visibility (default: private). One of: `public`, `private`.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "id": "example",
    "pendingSteps": []
  }
}
```

### Create source

Create a new source. Accepts text, qna, and link source types. File sources require a dedicated endpoint. Ticket and Notion sources are not accepted. The source starts training immediately, so no separate training call is needed. It is returned as untrained and flips to trained when it is live, or failed if training did not land; poll GET /agents/{agentId}/sources/{sourceId} to follow it.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Type (`type`, text, required): Type. One of: `text`, `qna`, `link`.
- Name (`name`, text): Name. Only when Type is text or qna.
- Content (`content`, text): Content. Only when Type is text.
- Questions (`questions`, list): Questions. Only when Type is qna.
- Answer (`answer`, text): Answer. Only when Type is qna.
- URL (`url`, text): Url. Only when Type is link.
- Link type (`link_type`, text): Link type. Only when Type is link. One of: `individual`, `sitemap`, `crawl`.
- Exclude paths (`exclude_paths`, list): Exclude paths. Only when Type is link.
- Include only paths (`include_only_paths`, list): Include only paths. Only when Type is link.
- Slow scraping (`slow_scraping`, true/false): Slow scraping. Only when Type is link.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "createdAt": "example",
    "id": "example",
    "metadata": {},
    "name": "example",
    "size": 1,
    "status": "untrained",
    "type": "link"
  }
}
```

### Delete agent

Permanently deletes an agent and all its sources. Also disconnects any active integrations (Slack, WhatsApp, etc.). This action is irreversible.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "success": true
  }
}
```

### Delete source

Delete a source. Its knowledge is removed from the agent immediately; the response carries the final state (deleted, or toBeDeleted while the purge finishes).

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Source ID (`source_id`, text, required): The source ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "createdAt": "example",
    "id": "example",
    "metadata": {},
    "name": "example",
    "size": 1,
    "status": "untrained",
    "type": "link"
  }
}
```

### Export conversations

Export all conversations with full message history for an agent. Includes conversations from all sources. Tool results are sanitized to remove internal data. Supports cursor-based pagination. Pass conversationId to fetch a single conversation from any source (widget, API, WhatsApp, etc.). Pass include=summary to omit message bodies for a cheaper triage pass, source to restrict to one or more conversation sources, and startDate / endDate to restrict to a createdAt window. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Cursor (`cursor`, text): Opaque cursor from a previous response to fetch the next page
- Limit (`limit`, number): Number of items per page (1 to 20, default 20). From 1.0 to 20.0.
- Start date (`start_date`, date and time): Only return conversations created at or after this point. Accepts a calendar date (YYYY-MM-DD, interpreted as the start of that day in UTC) or an ISO 8601 date-time.
- End date (`end_date`, date and time): Only return conversations created at or before this point. Accepts a calendar date (YYYY-MM-DD, interpreted as the *end* of that day in UTC, so the day itself is included) or an ISO 8601 date-time.
- Conversation ID (`conversation_id`, text): Return only the conversation with this ID. Use this to fetch a single conversation from any source (widget, API, WhatsApp, etc.).
- Include (`include`, text): Whether to include message bodies. summary omits them and skips reading them from the database , use it to triage a page cheaply, then re-request a specific conversation with conversationId. Defaults to messages. One of: `summary`, `messages`.
- Source (`source`, text): Comma-separated conversation sources to include, e.g. API,WhatsApp. Omit for all sources.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": [],
    "pagination": {
      "cursor": "example",
      "hasMore": false,
      "total": 1
    }
  }
}
```

### Get a conversation

Get conversation metadata and its most recent messages. The pagination cursor can be used with the list messages endpoint to fetch older messages. Only returns conversations created through the API. To fetch a conversation from any source (widget, WhatsApp, etc.), use GET /agents/{agentId}/conversations/export?conversationId={conversationId} instead.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Conversation ID (`conversation_id`, text, required): The conversation ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": {
      "createdAt": 1,
      "id": "example",
      "messages": [],
      "parentConversationId": "example",
      "parentSummary": "example",
      "status": "ongoing",
      "title": "example",
      "updatedAt": 1,
      "userId": "example"
    },
    "pagination": {
      "cursor": "example",
      "hasMore": false,
      "total": 1
    }
  }
}
```

### Get agent

Get a single agent by ID.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "allowedDomains": [],
    "autoRetrain": false,
    "blockedCountries": [],
    "channelInstructions": {
      "android_sdk": "example",
      "api": "example",
      "center_stage": "example",
      "chat_widget": "example",
      "email": "example",
      "help_page": "example",
      "instagram": "example",
      "ios_sdk": "example",
      "messenger": "example",
      "phone": "example",
      "salesforce": "example",
      "search": "example",
      "side_panel": "example",
      "slack": "example",
      "whatsapp": "example",
      "zendesk": "example",
      "zendesk_messaging": "example"
    },
    "createdAt": "example",
    "creditLimit": 1,
    "creditsUsed": 1,
    "id": "example",
    "initialMessages": [],
    "instructions": "example",
    "ipRateLimits": {
      "limit": 1,
      "message": "example",
      "timeframe": 1
    },
    "lastMessageAt": "example",
    "lastTrainedAt": "example",
    "model": "gpt-4o",
    "name": "example",
    "notificationsSettings": {
      "dailyConversations": {
        "active": false,
        "emails": []
      },
      "dailyLeadsCollected": {
        "active": false,
        "emails": []
      }
    },
    "size": 1,
    "spamSettings": {
      "enabled": false,
      "prompt": "example"
    },
    "status": "untrained",
    "styles": {
      "centerStage": {
        "accentColorEnabled": false,
        "accentSyncWithIcon": false,
        "closeOnOutsideClick": false,
        "dismissableNotice": "example",
        "displayName": "example",
        "enabled": false,
        "footer": "example",
        "headerColor": "example",
        "messagePlaceholder": "example",
        "showAttachments": false,
        "showChatBubble": false,
        "showCopyButton": false,
        "showDataSource": false,
        "showDictation": false,
        "showFeedback": false,
        "showVoiceMode": false,
        "suggestedMessages": [],
        "theme": "light",
        "tintedGrayscale": {
          "enabled": false,
          "hue": 0,
          "shade": -4,
          "tint": 0
        },
        "typography": {
          "fontFamily": "example",
          "fontSize": "example"
        },
        "userMessageColor": "example",
        "welcomeMessage": "example"
      },
      "chat": {
        "alignChatButton": "left",
        "autoOpenChatWindowAfter": 1,
        "buttonColor": "example",
        "dismissableNotice": "example",
        "displayName": "example",
        "footer": "example",
        "headerColor": "example",
        "messagePlaceholder": "example",
        "mobile": {
          "autoOpenChatWindowAfter": {
            "enabled": false,
            "value": 1
          },
          "initialMessages": {
            "enabled": false,
            "value": []
          },
          "showAutoOpen": false
        },
        "showAttachments": false,
        "showCopyButton": false,
        "showDictation": false,
        "showFeedback": false,
        "showVoiceMode": false,
        "theme": "light",
        "userMessageColor": "example"
      }
    },
    "suggestedMessages": [],
    "temp": 0,
    "visibility": "public",
    "voiceSettings": {
      "allowInterruptions": false,
      "allowTextInput": false,
      "endConversationAfterSilenceSeconds": 10,
      "errorMessage": "example",
      "initialMessage": "example",
      "maxCallDurationSeconds": 1,
      "maxConcurrentSessions": 1,
      "maxDailyCallsPerUser": 1,
      "model": "gpt-4o",
      "recordings": {
        "enabled": false,
        "retentionDays": 0
      },
      "temperature": 0,
      "transcriber": {
        "activationThreshold": 0,
        "language": "example",
        "minSilenceDuration": 0.1,
        "model": "example"
      },
      "voice": {
        "instructions": "example",
        "similarity": 0,
        "speed": 0.7,
        "stability": 0,
        "voiceName": "example"
      }
    }
  }
}
```

### Get source

Get a single source by ID.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Source ID (`source_id`, text, required): The source ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "createdAt": "example",
    "id": "example",
    "metadata": {},
    "name": "example",
    "size": 1,
    "status": "untrained",
    "type": "link"
  }
}
```

### Get sources summary

Get aggregated counts and sizes for each source type, plus a flag if the chatbot knowledge base requires a retrain to reflect any changes

**Inputs**

- Agent (`agent_id`, text, required): The agent ID

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "files": {
      "count": 1,
      "size": 1
    },
    "links": {
      "count": 1,
      "size": 1
    },
    "notionPages": {
      "count": 1,
      "size": 1
    },
    "qnas": {
      "count": 1,
      "size": 1
    },
    "salesforceCases": {
      "count": 1,
      "size": 1
    },
    "shouldRetrain": false,
    "texts": {
      "count": 1,
      "size": 1
    },
    "zendeskTickets": {
      "count": 1,
      "size": 1
    }
  }
}
```

### List agents

Get a paginated list of all agents for the authenticated account. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Cursor (`cursor`, text): Opaque cursor from a previous response to fetch the next page
- Limit (`limit`, number): Number of items per page (1 to 100, default 20). From 1.0 to 100.0.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": [],
    "pagination": {
      "cursor": "example",
      "hasMore": false,
      "total": 1
    }
  }
}
```

### List conversation messages

List all messages in a conversation with cursor-based pagination. Messages are returned in chronological order within each page, paginating backward from newest. The cursor from the get-conversation endpoint works here. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Conversation ID (`conversation_id`, text, required): The conversation ID
- Cursor (`cursor`, text): Opaque cursor from a previous response to fetch the next page
- Limit (`limit`, number): Number of items per page (1 to 100, default 20). From 1.0 to 100.0.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": [],
    "pagination": {
      "cursor": "example",
      "hasMore": false,
      "total": 1
    }
  }
}
```

### List conversations

List conversations created through the API for an agent, ordered by createdAt date. Conversations from other sources (widget, WhatsApp, etc.) are not included; use Search conversations or Export conversations for those. Supports cursor-based pagination. Pass startDate and/or endDate to restrict the results to a createdAt window. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Cursor (`cursor`, text): Opaque cursor from a previous response to fetch the next page
- Limit (`limit`, number): Number of items per page (1 to 100, default 20). From 1.0 to 100.0.
- Start date (`start_date`, date and time): Only return conversations created at or after this point. Accepts a calendar date (YYYY-MM-DD, interpreted as the start of that day in UTC) or an ISO 8601 date-time.
- End date (`end_date`, date and time): Only return conversations created at or before this point. Accepts a calendar date (YYYY-MM-DD, interpreted as the *end* of that day in UTC, so the day itself is included) or an ISO 8601 date-time.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": [],
    "pagination": {
      "cursor": "example",
      "hasMore": false,
      "total": 1
    }
  }
}
```

### List conversations for a user

List conversations created through the API for a specific user under an agent, ordered by last activity. Conversations from other sources (widget, WhatsApp, etc.) are not included; use Search conversations with userId to find them, and Export conversations to read their messages. Supports cursor-based pagination. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- API user ID (`api_user_id`, text, required): The user ID (URL-safe characters only: letters, digits, hyphens, underscores, dots)
- Cursor (`cursor`, text): Opaque cursor from a previous response to fetch the next page
- Limit (`limit`, number): Number of items per page (1 to 100, default 20). From 1.0 to 100.0.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": [],
    "pagination": {
      "cursor": "example",
      "hasMore": false,
      "total": 1
    }
  }
}
```

### List sources

Get a paginated list of sources for an agent. Ticket sources are excluded. For link sources only individual or sitemap/crawl parent links are returned with aggregated children metadata. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Cursor (`cursor`, text): Opaque cursor from a previous response to fetch the next page
- Limit (`limit`, number): Number of items per page (1 to 100, default 20). From 1.0 to 100.0.
- Type (`type`, text): Comma-separated source types to filter by. Allowed values: link, file, qna, notionPage, text
- Name (`name`, text): Partial (case-insensitive) name match

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": [],
    "pagination": {
      "cursor": "example",
      "hasMore": false,
      "total": 1
    }
  }
}
```

### Search conversations

Search an agent's conversations by text, filters, or both. With query, results are ranked and carry a highlighted snippet; without it, most recently active first. Filters combine with AND; comma-separated values within a filter with OR. Covers conversations created since the 1st of the month 12 months ago (UTC), activity-date filters included. Results lag new messages by a few seconds. A page can hold fewer than limit items, even none, while hasMore is true; keep paging. Read messages via export with conversationId. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Start date (`start_date`, date and time): Created at or after this point (YYYY-MM-DD or ISO 8601). Must be inside the searchable window.
- End date (`end_date`, date and time): Created at or before this point (YYYY-MM-DD, inclusive, or ISO 8601).
- Query (`query`, text): Free-text search over messages and titles.
- Source (`source`, text): Comma-separated sources, e.g. API,WhatsApp.
- Sentiment (`sentiment`, text): Comma-separated: positive, neutral, negative, or unspecified for none.
- Topic (`topic`, text): Comma-separated topic names, or unspecified for none.
- API user ID (`api_user_id`, text): Comma-separated user IDs.
- Activity state (`activity_state`, text): Comma-separated: ongoing, ended, taken_over, paused.
- Feedback (`feedback`, text): Comma-separated message ratings: positive, negative.
- Escalated (`escalated`, text): true: only conversations escalated to a human (ticket or live-chat handoff). One of: `true`.
- Action type (`action_type`, text): Comma-separated action types that ran, e.g. collect-leads.
- Tool (`tool`, text): Comma-separated tool names that were called.
- Tool outcome (`tool_outcome`, text): Comma-separated tool result statuses, e.g. error. Scoped to tool when set.
- Procedure (`procedure`, text): Comma-separated procedure names that ran.
- Procedure outcome (`procedure_outcome`, text): Comma-separated procedure run statuses. Scoped to procedure when set.
- Has voice (`has_voice`, text): Whether a voice session took place. One of: `true`, `false`.
- Updated after (`updated_after`, date and time): Last active at or after this point (YYYY-MM-DD or ISO 8601).
- Updated before (`updated_before`, date and time): Last active at or before this point (YYYY-MM-DD, inclusive, or ISO 8601).
- Cursor (`cursor`, text): pagination.cursor from the previous page. Keep the other parameters unchanged.
- Limit (`limit`, number): Items per page (1 to 25, default 25). From 1.0 to 25.0.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": [],
    "pagination": {
      "cursor": "example",
      "hasMore": false
    }
  }
}
```

### Toggle auto-retrain

Enables or disables automatic retraining. When enabled, the agent retrains every 7 days to reflect any source changes.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Enabled (`enabled`, true/false, required): true = retrain every 7 days, false = never

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "success": true
  }
}
```

### Update agent

Partially updates an agent. Only provided fields are changed.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Name (`name`, text): Agent name
- Instructions (`instructions`, text): System prompt (max 30,000 characters)
- Channel instructions (`channel_instructions`, object): Per-channel instruction overrides (max 30,000 characters each)
- Model (`model`, text): AI model. One of: `gpt-oss-120b`, `gpt-oss-20b`, `gpt-5.2`, `gpt-5.5`, `gpt-5.6-terra`, `gpt-6.1-sol`, `gpt-6-luna`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5`, and 18 more.
- Temp (`temp`, number): Temperature (0 to 1). From 0.0 to 1.0.
- Visibility (`visibility`, text): Visibility. One of: `public`, `private`.
- Allowed domains (`allowed_domains`, list): Allowed embed domains
- Suggested messages (`suggested_messages`, list): Suggested messages
- Initial messages (`initial_messages`, list): Initial messages
- Credit limit (`credit_limit`, number): Per-agent credit limit (null = no limit)
- Notifications settings (`notifications_settings`, object): Email notification settings (null = disable all notifications)
- IP rate limits (`ip_rate_limits`, object): IP-based rate limit settings (partial update; null = reset to defaults)
- Spam settings (`spam_settings`, object): Spam detection settings (null = disable spam detection)
- Voice settings (`voice_settings`, object): Voice mode configuration (null = disable voice mode)
- Blocked countries (`blocked_countries`, list): ISO 3166-1 alpha-2 country codes to block (null = remove all blocking)

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "success": true
  }
}
```

### Update agent styles

Update the visual styles for an agent.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Styles (`styles`, object, required): Styles.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "success": true
  }
}
```

### Update conversation status

Update the activity state of a conversation.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Conversation ID (`conversation_id`, text, required): The conversation ID
- Status (`status`, text, required): Target activity state for the conversation. One of: `ongoing`, `paused`, `ended`.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": {
      "id": "example",
      "status": "ongoing"
    }
  }
}
```

### Update message feedback

Set or clear feedback on an assistant message. Use "positive" or "negative" to set feedback, or null to remove existing feedback.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Conversation ID (`conversation_id`, text, required): The conversation ID
- Message ID (`message_id`, text, required): The message ID
- Feedback (`feedback`, text, required): Set feedback: "positive", "negative", or null to clear

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "data": {
      "createdAt": 1,
      "feedback": "positive",
      "id": "example",
      "metadata": {
        "score": 1
      },
      "parts": [],
      "role": "user"
    }
  }
}
```

### Update source

Update an existing source. Accepts text, qna, and link sources. File sources require a dedicated endpoint. A content change retrains the source immediately (status updated until it is live again). Link URL is immutable, so to change it, delete and recreate the source. Ticket and Notion sources are not accepted.

**Inputs**

- Agent (`agent_id`, text, required): The agent ID
- Source ID (`source_id`, text, required): The source ID
- Name (`name`, text): Name.
- Content (`content`, text): Content.
- Questions (`questions`, list): Questions.
- Answer (`answer`, text): Answer.
- Exclude paths (`exclude_paths`, list): Exclude paths.
- Include only paths (`include_only_paths`, list): Include only paths.
- Slow scraping (`slow_scraping`, true/false): Slow scraping.

**Outputs**

- `response` (object): Response.

**Example output**

```json
{
  "response": {
    "createdAt": "example",
    "id": "example",
    "metadata": {},
    "name": "example",
    "size": 1,
    "status": "untrained",
    "type": "link"
  }
}
```
