> ## Documentation Index > Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt > Use this file to discover all available pages before exploring further. # Get threads ## OpenAPI ````yaml /openapi.json get /threads openapi: 3.1.1 info: title: Anima API version: 0.1.0 description: >- The Anima API provides programmatic access to unified infrastructure for AI agents: create and manage agents; send and receive email; place phone calls and send/receive SMS and voice; store and retrieve vault credentials; manage agent identity; and configure webhooks for real-time events. Authenticate using a Bearer token or an API key passed via the X-API-Key header. contact: name: Anima Labs url: https://useanima.sh email: support@useanima.sh license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.useanima.sh/v1 description: Production security: - BearerAuth: [] - ApiKeyAuth: [] paths: /threads: get: operationId: thread.list parameters: - name: channel in: query schema: default: EMAIL enum: - EMAIL type: string description: >- Channel to list conversations for. EMAIL is currently the only supported value — SMS/MMS conversations are listed by GET /sms/threads, which models them as a phone-number pair rather than a reply chain. allowEmptyValue: true allowReserved: true - name: agentId in: query schema: type: string pattern: ^[cC][^\s-]{8,}$ description: >- Filter conversations to one agent. Optional for master keys (omit for every agent in the org); ignored for agent keys, which always see only their own. allowEmptyValue: true allowReserved: true - name: inboxId in: query schema: type: string pattern: ^[cC][^\s-]{8,}$ description: >- Filter conversations to one inbox — the precise way to read a single mailbox. allowEmptyValue: true allowReserved: true - name: direction in: query schema: enum: - INBOUND - OUTBOUND type: string description: >- Only conversations containing a message in this direction. `OUTBOUND` is a Sent view. Note that the returned counts then describe the MATCHING messages, not the thread's full length. allowEmptyValue: true allowReserved: true - name: labels in: query schema: type: array items: type: string minLength: 1 maxLength: 64 maxItems: 50 description: >- Filter to messages carrying ALL of these labels (e.g. `urgent` + `unread` means urgent AND still unread). Case-insensitive. System labels: `unread`, `read`, `archived`, `spam`. style: deepObject explode: true allowEmptyValue: true allowReserved: true - name: includeSpam in: query schema: default: false type: boolean description: >- Include messages classified as spam on arrival. They are excluded by default. Naming `spam` in `labels` also counts as asking for it, so a deliberate spam query is never silently emptied by this default. allowEmptyValue: true allowReserved: true - name: includeArchived in: query schema: default: false type: boolean description: >- Include messages carrying the `archived` label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming `archived` in `labels` also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest. allowEmptyValue: true allowReserved: true - name: deleted in: query schema: default: exclude enum: - exclude - include - only type: string description: >- How to treat messages moved to Trash. `exclude` (default) hides them, so deleted mail disappears from every ordinary listing. `only` returns nothing but Trash. `include` ignores the distinction. Deletion is reversible — see DELETE /messages/{id} and POST /messages/{id}/restore. allowEmptyValue: true allowReserved: true - name: limit in: query schema: default: 20 type: integer minimum: 1 maximum: 100 description: Maximum conversations to return per page (1–100, default 20) allowEmptyValue: true allowReserved: true - name: offset in: query schema: default: 0 type: integer minimum: 0 description: Conversations to skip, for paging through the list allowEmptyValue: true allowReserved: true responses: '200': description: OK content: application/json: schema: type: object properties: items: type: array items: type: object properties: threadId: type: string description: >- Conversation identifier — the id of the thread's first message. Pass to GET /email?threadId= to read the messages. agentId: type: string description: Agent that owns this conversation subject: anyOf: - type: string - type: 'null' description: >- Subject of the most recent message in the thread, or null if it has none participants: type: array items: type: string description: >- Distinct senders and To recipients across the thread, lowercased and de-duplicated, including the agent's own address. NOT exhaustive: Cc'd correspondents are absent (they are recorded on the message, but this list is built from the From and To fields only), and Bcc recipients are absent because they are never recorded at all — by design. Treat this as 'who is visibly on the thread', not as the full recipient set; read the messages themselves if you need every address. messageCount: type: integer description: >- Messages in the thread matching this query. Equals the thread's full length for an unfiltered listing; under a `direction` or label filter it counts only the matching messages, since a thread is listed when ANY of its messages matches. unreadCount: type: integer description: >- How many of those messages still carry the `unread` label — what a thread list needs to be worth scanning. lastMessageAt: type: string format: date-time description: >- When the most recent message arrived or was sent — the sort key for this list lastMessageSnippet: type: string description: >- First 140 characters of the most recent message, quoted chain already stripped where possible, so a thread list costs a snippet rather than a mail history lastMessageDirection: enum: - INBOUND - OUTBOUND type: string description: >- Whether the most recent message was received or sent — i.e. is the ball ours required: - threadId - agentId - subject - participants - messageCount - unreadCount - lastMessageAt - lastMessageSnippet - lastMessageDirection description: Summary of one email conversation description: Conversation summaries, most recent activity first total: type: integer description: Total conversations matching the query hasMore: type: boolean description: Whether more conversations exist past this page required: - items - total - hasMore description: Paginated list of email conversations components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer ApiKeyAuth: type: apiKey in: header name: X-API-Key description: 'API key for programmatic access. Pass as: X-API-Key: ' ````