---
title: "POST /messages/search/semantic"
method: POST
path: "/messages/search/semantic"
---

# POST /messages/search/semantic

`POST /messages/search/semantic`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/messages/search/semantic`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Request body

- object: Semantic search parameters
  - `query` string, required: Natural language search query
  - `agentId` string: Filter results to a specific agent
  - `inboxId` string: Filter to one inbox — messages delivered to it (inbound) or sent from it (outbound). The precise way to read a single mailbox when an agent owns several.
  - `fromAddress` string: Filter by sender address, matched exactly (case-sensitive). On inbound mail this is the counterparty; on outbound it is the agent identity the mail was sent from.
  - `toAddress` string: Filter by recipient address, matched exactly (case-sensitive). Note that outbound messages store every recipient in one comma-joined value, so an exact filter matches a multi-recipient send only when given that same joined string — prefer `inboxId` to scope outbound mail to a mailbox.
  - `limit` integer: Maximum number of results to return
  - `threshold` number: Minimum similarity score threshold (0-1)

## Response `200`

OK

- object: Semantic search results
  - `results` object[], required: List of messages ranked by semantic similarity
    - `id` string, required: Unique message identifier
    - `content` string, required: Message content text
    - `similarity` number, required: Cosine similarity score between 0 and 1
    - `channel` string, required: Communication channel (e.g. email, sms)
    - `direction` string, required: Message direction (inbound or outbound)
    - `createdAt` string, date-time, required: ISO 8601 timestamp of message creation
    - `agentId` string, required: Identifier of the agent associated with the message
    - `inboxId` string, nullable, required: ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox. Pass it back as `inboxId` to scope a later search to that one mailbox.

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)