> ## Documentation Index > Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt > Use this file to discover all available pages before exploring further. # List interactions > Returns the workspace's synced email threads and meetings, from every connected mailbox and calendar, with their AI analysis and the records they are linked to. Each row is the full interaction, including message bodies and meeting transcripts, so keep `limit` small. By default the list pages with a cursor, newest synced first: pass `limit`, then send `meta.pagination.next_cursor` back as `cursor`. A `sort`, or `page` (as a parameter or inside `filters`), switches to page-number paging, where `meta.pagination` holds `page`, `limit`, `totalPages`, `count` and `hasMore`. See [Pagination](/api-reference/pagination). To list only the interactions linked to one record, send `{"objectId": ""}` in `filters`. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_interactions_list`](https://docs.heliyos.ai/mcp/tools/timeline-and-activity#heliyos-interactions-list). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/platform/interactions openapi: 3.0.3 info: title: Heliyos API version: 1.0.0 description: >- The REST API for Heliyos, the AI operating system for revenue. Every request is scoped to the workspace that owns the API key. Responses are JSON in a `{ meta, data }` envelope; errors use `{ message, error: { code, message, details } }`. contact: name: Heliyos support email: soham@heliyos.ai url: https://www.heliyos.ai servers: - url: https://api-prod.heliyos.ai description: Production security: - bearerAuth: [] tags: - name: Workspace description: >- The workspace your API key belongs to, and the log of credits it has used. Every other call in this API is scoped to this workspace. - name: Schemas description: >- Objects are your record types: companies, people, deal pipelines and any custom objects you add. Each object has fields, and a field's type decides what its records can hold. - name: Records description: >- Records are the rows of an object (base schema): companies, people, deals and custom objects. A record holds field values keyed by the object's field keys and links to other records. - name: Timeline description: >- The AI-written timeline of a company, person or deal: summary entries Heliyos writes on a schedule. For the exact change history see Activities, and for emails and meetings see Interactions. - name: Activities description: >- The change history of records and tasks: who created, changed or deleted what, and when. People, workers and the system each appear as the actor on the changes they make. - name: Interactions description: >- Email threads and meetings synced from connected mailboxes and calendars, linked to the people and companies they involve. - name: Notes description: >- Free-text notes, optionally linked to records, tasks and interactions. Notes show up on the timeline of every record they are linked to, and workers read them as customer memory. - name: Tasks description: >- Work items for people and workers, optionally linked to records. A task can be assigned to people, to workers, or both, and workers can be started on it directly. - name: Workers and runs description: >- Workers are the AI teammates of your workspace (the API calls them agents). Define what each one does and what starts it, ask Heliyos to do work, and follow every run, its steps and the reviews it waits on. - name: Reviews description: >- Reviews keep the team in control of consequential work. When a worker wants to send an email, change a deal, book a meeting, act in a connected app or needs a person's answer, the action waits as a review until someone approves or rejects it. - name: Scouts description: >- Scouts watch companies and the web for events such as funding rounds, product launches, leadership changes or press coverage, and record each finding as a signal. A workspace Scout defines what to look for; company Scouts are its copies running on individual companies. - name: Signals description: >- Signals are what Scouts find: one event, such as a funding round or a new executive, with a summary, its sources and the company it is about. New signals are unread until you mark them read. - name: Watchlist description: >- The watchlist is the set of companies your workers monitor. Each watched company uses one Watcher from your plan: the workers keep it enriched, pull in its emails and meetings, and run Scouts on it. - name: Knowledge base description: >- What your workers know about the business: the business context, four fixed texts (products, pain points, value proposition, qualification criteria) and any custom entries your team adds. Workers read it on their next run. Files your workers read live under Files, with kind `knowledge_base`. - name: Files description: >- Knowledge base files that workers read, and files attached to records, tasks and other resources. The API calls them attachments. Uploading takes three calls: get an upload URL, send the bytes to it, then create the file. - name: Labels description: >- Label groups that sort your email threads, for example Intent or Pricing questions. Heliyos files each classified thread under a group, and each group holds the more specific labels it brings together. The API calls them classification labels. - name: Team description: >- The people in your workspace and their roles: joined members and pending invitations. Inviting someone sends them an email. - name: Notification settings description: >- Which workspace events send notification emails, how often, and to whom. There is one settings document per workspace, shared by everyone in it. paths: /v1/platform/interactions: get: tags: - Interactions summary: List interactions description: >- Returns the workspace's synced email threads and meetings, from every connected mailbox and calendar, with their AI analysis and the records they are linked to. Each row is the full interaction, including message bodies and meeting transcripts, so keep `limit` small. By default the list pages with a cursor, newest synced first: pass `limit`, then send `meta.pagination.next_cursor` back as `cursor`. A `sort`, or `page` (as a parameter or inside `filters`), switches to page-number paging, where `meta.pagination` holds `page`, `limit`, `totalPages`, `count` and `hasMore`. See [Pagination](/api-reference/pagination). To list only the interactions linked to one record, send `{"objectId": ""}` in `filters`. operationId: listInteractions parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Interactions per page, 1 to 100. Defaults to 20. example: 20 - name: cursor in: query required: false schema: type: string maxLength: 200 description: >- next_cursor from the previous page; only valid with the default sort. description: >- The `next_cursor` from the previous page. Only valid without a `sort` (a 400 otherwise). When you send both `cursor` and `page`, `cursor` wins. - name: page in: query required: false schema: type: integer minimum: 1 description: >- A page number, starting at 1, for page-number paging. Pages are `limit` interactions long. - name: filters in: query required: false schema: type: string maxLength: 20000 description: >- JSON-encoded filter object (search, filters, sort, page, pageSize). Optional. pageSize above 200 is clamped to 200. description: >- A JSON object, URL-encoded. Keys: - `objectId` (id): only interactions linked to this record. - `channelType` (string or array): `email`, `meeting`, or both (an array or a comma-separated string). - `categoryIds` (string or array): only interactions with any of these label ids. - `search` (string): case-insensitive text match on the subject, title, summary, message previews, takeaways, transcript and participant addresses. - `uniqByRelationships` (any non-empty value): keep one interaction per distinct set of linked records. - `sort` (array): `{ "field", "direction" }` with direction `asc` or `desc`. Useful fields: `thread_date` (newest email message), `start_time` (meeting start), `createdAt` (when synced). - `filters` (array): conditions `{ "field", "operator", "value", "conjunction" }`. Conditions with `"conjunction": "and"` must all match. Conditions without it, or with `"or"`, are combined with OR, so set `"conjunction": "and"` on every condition you need to hold. Operators: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `empty`, `not_empty`, `in`, `not_in`, `greater_than`, `less_than`, `greater_than_equal`, `less_than_equal`, `after`, `before`, `between` (value `{"startDate","endDate"}` as a JSON string), and `is` / `is_not` for `participants`. Special fields: `channelType`, `categoryIds`, `participants` (meeting invitee addresses), `hasAgentDraft` (true for threads holding a worker's unsent draft), and `relationships..` to match a linked record's field value, for example `relationships.company.company_name`. - `page` and `pageSize`: page-number paging. `pageSize` is capped at 200. example: >- {"objectId":"66f1a8c3e4b0a1b2c3d4e5f6","channelType":"email","sort":[{"field":"thread_date","direction":"desc"}]} responses: '200': description: A page of interactions. content: application/json: schema: type: object required: - meta - data properties: meta: type: object required: - message properties: message: type: string description: A human-readable summary of the result. pagination: $ref: '#/components/schemas/KeysetPagination' data: type: array items: $ref: '#/components/schemas/Interaction' example: meta: message: Meetings fetched successfully. pagination: limit: 20 next_cursor: NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2 data: - _id: 6728b1c2d3e4f5a6b7c8d9e0 organizationId: 66a0f1e2d3c4b5a697887766 integrationId: 66a0f1e2d3c4b5a697885555 channel: type: email email: priya@example.com subject: Security questionnaire for Northwind Traders thread_id: thr_7f3a9c threads: - message_id: msg_91b2 thread_id: thr_7f3a9c subject: Security questionnaire for Northwind Traders snippet: >- Hi Priya, attached is our standard questionnaire. Could you return it by Friday? date: 1762250400 from: - name: Ana Silva email: ana.silva@northwind.example.com to: - name: Priya Patel email: priya@example.com cc: [] unread: false starred: false relationships: - objectId: 66f1a8c3e4b0a1b2c3d4e5f6 objectType: company schemaId: 66a0f1e2d3c4b5a697880001 object: _id: 66f1a8c3e4b0a1b2c3d4e5f6 objectType: company baseSchemaId: 66a0f1e2d3c4b5a697880001 isAgentAssigned: true data: company_name: Northwind Traders domain: northwind.example.com categoryIds: [] classificationLabels: [] summary: >- Northwind sent its security questionnaire and wants it back by Friday. sentiment: Positive sentimentReason: The buyer is moving the deal forward. isSummarized: true createdAt: '2026-11-04T10:00:05.000Z' - _id: 6728b1c2d3e4f5a6b7c8d9e1 organizationId: 66a0f1e2d3c4b5a697887766 integrationId: 66a0f1e2d3c4b5a697885556 channel: type: meeting email: priya@example.com title: Northwind Traders pricing review when: start_time: 1762329600 end_time: 1762331400 start_timezone: UTC end_timezone: UTC participants: - email: priya@example.com status: 'yes' - email: ana.silva@northwind.example.com status: 'yes' meetingStatus: NOT_STARTED relationships: [] summary: '' sentiment: null isSummarized: false createdAt: '2026-11-04T10:05:00.000Z' '400': description: >- VALIDATION_FAILED: `filters` is not a JSON object, has a malformed condition or `objectId`, or `cursor` was sent with a sort. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: KeysetPagination: type: object description: >- Cursor paging. Pass `next_cursor` back as `cursor` with the same `limit` for the next page. required: - limit properties: limit: type: integer description: The page size used for this page. example: 20 next_cursor: type: string description: Cursor for the next page. Absent on the last page. Interaction: type: object description: >- A synced email thread (`channel.type` `email`) or calendar meeting (`channel.type` `meeting`). Heliyos stores the provider's data and adds AI analysis. Fields depend on the channel and on how far the analysis has got; treat every field except `_id`, `organizationId` and `channel` as optional, and ignore fields you do not recognise. additionalProperties: true properties: _id: $ref: '#/components/schemas/ObjectId' organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace. channel: type: object properties: type: type: string enum: - email - meeting description: '`email` for an email thread, `meeting` for a calendar event.' email: type: string description: >- The connected mailbox or calendar the interaction was synced from. integrationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The connected mailbox or calendar integration that synced it. relationships: type: array description: >- The records this interaction is linked to (matched from participants' addresses). Each entry carries `objectId`, `objectType` and `schemaId`, plus `object`: the linked record's `_id`, `objectType`, `baseSchemaId`, `isAgentAssigned` and all of its field values in `data`. items: type: object additionalProperties: true properties: objectId: $ref: '#/components/schemas/ObjectId' objectType: type: string description: '`company`, `people` or `deals`.' schemaId: type: string nullable: true description: The linked record's object id. object: type: object additionalProperties: true description: The linked record. Absent when the record no longer exists. categoryIds: type: array items: type: string description: Ids of the labels applied to this interaction. classificationLabels: type: array description: >- The labels in `categoryIds`, resolved (`_id`, `name`, `description`, `color`, `labels`). items: type: object additionalProperties: true summary: type: string description: The AI summary. Empty until the interaction is analysed. sentiment: type: string nullable: true description: >- The other party's sentiment, written by the analysis. Usually `Positive`, `Negative`, `Neutral`, `Excited` or `Do Not Contact`. Null until analysed. sentimentReason: type: string description: Why the analysis chose that sentiment. isSummarized: type: boolean description: Whether the AI analysis has run. createdAt: allOf: - $ref: '#/components/schemas/Timestamp' description: >- When Heliyos first synced it. Some older interactions store this as text. lastMessageDate: type: integer description: >- The newest message time (email) or the start time (meeting), in Unix seconds. subject: type: string description: 'Email: the thread subject.' thread_id: type: string description: 'Email: the mail provider''s thread id.' threads: type: array description: 'Email: the messages in the thread, oldest first.' items: $ref: '#/components/schemas/InteractionMessage' title: type: string description: 'Meeting: the event title.' when: type: object description: 'Meeting: start and end, in Unix seconds, with time zones.' properties: start_time: type: integer end_time: type: integer start_timezone: type: string end_timezone: type: string participants: type: array description: >- Meeting: invitees, each with `email` and `status`, the response as the calendar provider reports it (for example `yes`, `no` or `maybe`). items: type: object additionalProperties: true properties: email: type: string status: type: string creator: type: object description: 'Meeting: who created the event (`name`, `email`).' additionalProperties: true conferencing: type: object description: 'Meeting: the video provider and join details.' additionalProperties: true meetingStatus: type: string description: >- Meeting: where recording and analysis stand. One of `NOT_STARTED`, `IN_PROGRESS`, `ANALYSING`, `COMPLETED`, `CANCELLED`, `RECORDING_NOT_PERMITTED`, `ABANDONED` or `ERROR`. transcript: type: array description: 'Meeting: the transcript, when the meeting was recorded.' items: type: object properties: timestamp: type: string speaker: type: string dialogue: type: string takeaways: type: string description: 'Meeting: takeaways from the analysis.' keyTakeaways: type: string description: 'Meeting: key takeaways from the analysis.' nextSteps: description: 'Meeting: next steps from the analysis, as text or a list.' oneOf: - type: string - type: array items: {} ErrorEnvelope: type: object required: - message - error properties: message: type: string description: Same as error.message. error: type: object required: - code - message properties: code: type: string enum: - VALIDATION_FAILED - UNAUTHENTICATED - FORBIDDEN_ACTION - NOT_FOUND - RATE_LIMITED - CONFLICT - INTERNAL message: type: string details: {} ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' InteractionMessage: type: object description: One message in an email thread. additionalProperties: true properties: message_id: type: string description: The mail provider's message id. thread_id: type: string description: The mail provider's thread id. subject: type: string description: The message subject. snippet: type: string description: A short plain-text preview. body: type: string description: The message body (HTML or text), when synced. date: type: integer description: When the message was sent, in Unix seconds. from: type: array items: type: object properties: name: type: string email: type: string description: Sender. to: type: array items: type: object properties: name: type: string email: type: string description: Recipients. cc: type: array items: type: object additionalProperties: true description: Copied recipients. unread: type: boolean description: Whether the message is unread in the mailbox. starred: type: boolean description: Whether the message is starred in the mailbox. attachments: type: array items: type: object additionalProperties: true description: Metadata for the files attached to the message. agentGenerated: type: boolean description: True when a worker wrote this message. isDraft: type: boolean description: True for a worker's unsent draft. securitySchemes: bearerAuth: type: http scheme: bearer description: >- A workspace API key, sent as `Authorization: Bearer heliyos_...`. Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.