# Search Conversations

> Search conversations for an organization.

Canonical URL: https://docs.botyard.io/docs/api/conversations/search_conversations_v1_orgs__org_id__conversations_search_post

`POST /v1/orgs/{org_id}/conversations/search`

Search conversations for an organization.

Access scoping:
- JWT users see their own user-scoped + all org-scoped conversations.
- API keys see only org-scoped conversations.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | yes | string |  |

## Request body

`application/json`: ConversationSearch (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bot_id` | string \| null | no | Filter by bot UUID |
| `bot_slug` | string \| null | no | Filter by bot slug — resolved to UUID server-side |
| `conversation_scope` | ConversationScope \| null | no |  |
| `deletion` | ConversationDeletionFilter \| null | no | Soft-deletion scope: active excludes deleted conversations, deleted returns only deleted conversations, and all returns both. |
| `metadata_filter` | object \| null | no |  |
| `where` | FilterNode_ConversationFilterField_ \| null | no | Filter DSL clause. AND'd in with the structural and flat filters above. See FilterNode for the recursive condition / and / or shape. |
| `message_search` | string \| null | no | Optional semantic query over embedded conversation messages. When set, conversation results are restricted to conversations with matching persisted message chunks, in addition to the structural and DSL filters. |
| `pinned_only` | boolean | no | Restrict results to conversations the authenticated user has pinned, regardless of recency — so the picker's pinned section can be fetched in full without paging through the recency-ordered list. AND'd in with the structural and DSL filters above (and still access-scoped). Always empty for API-key/bot callers, since pins are per-user. |
| `participated_only` | boolean | no | Restrict results to conversations the authenticated user has sent at least one message in. AND'd in with the structural, DSL, message-search and ``pinned_only`` filters above, and still access-scoped: having posted in a conversation never makes it visible. Always empty for API-key/bot callers, since it is a per-user view. |
| `limit` | integer | no |  |
| `offset` | integer | no |  |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Successful Response | PaginatedResponse_ConversationResponse_ |
| `default` | RFC 9457 Problem Details error response | ProblemDetails |

Full schemas: operation `search_conversations_v1_orgs__org_id__conversations_search_post` in the OpenAPI spec at https://api.botyard.io/openapi.json.