Authenticate all requests by setting the Authorization header to 'Bearer YOUR_TOKEN' where YOUR_TOKEN is your Intercom Access Token from the Developer Hub.
POST to /conversations/search with a JSON body containing a 'query' object. Simple single-condition searches use 'field', 'operator', and 'value' keys; compound searches use 'operator' (AND/OR) and a 'value' array of condition objects.
Searchable fields include 'state' (open, closed, snoozed), 'created_at', 'updated_at', 'assignee.id', 'tag.id', and others documented in the API reference — confirm field names against the docs before querying.
Control pagination with 'pagination.per_page' (max 150) and 'pagination.starting_after' (cursor from the previous response's 'pages.next.starting_after').
Extract conversation IDs and metadata from the 'conversations' array in the response; fetch full conversation detail with GET /conversations/{id} if you need message parts.
Combine multiple filters (e.g., state=open AND assignee.id=agent_123) using a compound AND query to narrow results before processing.
Known gotchas
The conversations search API is distinct from the data export API — exports only cover outbound-content engagement data; conversation retrieval must use search or the conversations list endpoint.
Cursor-based pagination means you cannot jump to an arbitrary page — you must walk through pages sequentially; store the cursor if you need to resume interrupted exports.
Search results reflect the state of conversations at the time of the query; rapidly updated conversations may appear differently if you fetch detail immediately after a bulk search.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp