> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List conversations

> Pages through the workspace's conversations, most recently active first (one with no message last). Filter with `filter[<key>][<op>]=<value>` (conditions are ANDed; `in` repeats the parameter), each key taking one condition, eq or in: `account`, `assignee`, `agent` (ids), `tag` (tag ids), `status_group` (not_started, active, done, archived), `channel` (email, slack, teams, portal, in_app_sdk), `kind` (support, customer_success), `priority` (normal, urgent). `last_message_at` takes a date (YYYY-MM-DD, UTC days) with eq, gt, gte, lt or lte, and may repeat to make a range. `outreach` (eq, true or false) keeps the conversations a digital worker's proactive email went out on (each is in GET /v1/outreach_emails), or the rest. Anything else is a 422. The order is by each conversation's latest message, so one that gets a message while you page moves ahead of your cursor: page again from the start to see it. A conversation is a thread an AI in the workspace handles, or could: an email, Slack or Teams thread, or a chat in the portal or the in-app widget. `kind` is support (a support AI's) or customer_success (any other AI's), null when no AI covers the thread. Which conversations a workspace reads follows its plan: with digital workers, every conversation (threads no AI covers included); with the support assistant alone, the support ones. `status` is the workspace's own status and `status_group` its group. `ai` says whether an AI wrote in it and, once closed, how it was resolved and why it closed; nothing records a customer confirming a resolution. `engineering_issue` is the issue it was handed to.



## OpenAPI

````yaml /api/statisfy-api.openapi.json get /v1/conversations
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/conversations:
    get:
      tags:
        - conversations
      summary: List conversations
      description: >-
        Pages through the workspace's conversations, most recently active first
        (one with no message last). Filter with `filter[<key>][<op>]=<value>`
        (conditions are ANDed; `in` repeats the parameter), each key taking one
        condition, eq or in: `account`, `assignee`, `agent` (ids), `tag` (tag
        ids), `status_group` (not_started, active, done, archived), `channel`
        (email, slack, teams, portal, in_app_sdk), `kind` (support,
        customer_success), `priority` (normal, urgent). `last_message_at` takes
        a date (YYYY-MM-DD, UTC days) with eq, gt, gte, lt or lte, and may
        repeat to make a range. `outreach` (eq, true or false) keeps the
        conversations a digital worker's proactive email went out on (each is in
        GET /v1/outreach_emails), or the rest. Anything else is a 422. The order
        is by each conversation's latest message, so one that gets a message
        while you page moves ahead of your cursor: page again from the start to
        see it. A conversation is a thread an AI in the workspace handles, or
        could: an email, Slack or Teams thread, or a chat in the portal or the
        in-app widget. `kind` is support (a support AI's) or customer_success
        (any other AI's), null when no AI covers the thread. Which conversations
        a workspace reads follows its plan: with digital workers, every
        conversation (threads no AI covers included); with the support assistant
        alone, the support ones. `status` is the workspace's own status and
        `status_group` its group. `ai` says whether an AI wrote in it and, once
        closed, how it was resolved and why it closed; nothing records a
        customer confirming a resolution. `engineering_issue` is the issue it
        was handed to.
      operationId: conversations_list
      parameters:
        - in: query
          name: limit
          required: false
          schema:
            default: 25
            maximum: 100
            minimum: 1
            type: integer
        - description: '`next_cursor` from the previous page'
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            default: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationPage'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    ConversationPage:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Conversation'
          title: Data
          type: array
        has_more:
          default: false
          title: Has More
          type: boolean
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      required:
        - data
      title: ConversationPage
      type: object
    Conversation:
      properties:
        account_id:
          anyOf:
            - type: string
            - type: 'null'
          description: The account it is about; null when none resolved
          title: Account Id
        activity_id:
          description: >-
            Its thread: on the timeline at GET /v1/activities/{activity_id} (a
            thread started in the portal or the in-app chat has none there)
          title: Activity Id
          type: string
        agent:
          anyOf:
            - $ref: '#/components/schemas/ConversationAgent'
            - type: 'null'
          description: The AI that covers it; null when none does
        ai:
          $ref: '#/components/schemas/ConversationAi'
        assignee:
          anyOf:
            - $ref: '#/components/schemas/ConversationAssignee'
            - type: 'null'
          description: The person it is assigned to
        channel:
          anyOf:
            - enum:
                - portal
                - in_app_sdk
                - email
                - slack
                - teams
                - ticket
              type: string
            - type: 'null'
          description: email, slack, teams, portal or in_app_sdk
          title: Channel
        close_reason:
          anyOf:
            - enum:
                - answered
                - no_reply
                - quiet
                - person
                - person_reply
              type: string
            - type: 'null'
          description: >-
            answered, no_reply, quiet, person (a person closed it) or
            person_reply (a person's reply settled it); null unless its status
            is Closed
          title: Close Reason
        closed_at:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO 8601 UTC; null unless its status is Closed (cleared on a reopen)
          title: Closed At
        created_at:
          description: ISO 8601 UTC
          title: Created At
          type: string
        customer_told_at:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            ISO 8601 UTC: when the customer was last told about the engineering
            issue
          title: Customer Told At
        engineering_issue:
          anyOf:
            - $ref: '#/components/schemas/ConversationEngineeringIssue'
            - type: 'null'
          description: The engineering issue it was handed to; null when none
        first_reply_at:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            ISO 8601 UTC: when the first reply, from the AI or a person, reached
            the customer
          title: First Reply At
        id:
          title: Id
          type: string
        kind:
          anyOf:
            - enum:
                - customer_success
                - support
              type: string
            - type: 'null'
          description: >-
            support (a support AI's conversation) or customer_success (any other
            AI's); null when no AI covers the thread
          title: Kind
        last_message_at:
          anyOf:
            - type: string
            - type: 'null'
          description: 'ISO 8601 UTC: its thread''s latest message'
          title: Last Message At
        outcome:
          anyOf:
            - enum:
                - knowledge
                - account_data
                - engineering
                - person
                - none
              type: string
            - type: 'null'
          description: >-
            knowledge, account_data, engineering, person or none; null unless
            its status is Closed
          title: Outcome
        priority:
          anyOf:
            - enum:
                - normal
                - urgent
              type: string
            - type: 'null'
          description: normal or urgent, as a person set it; null when nobody has
          title: Priority
        reopen_count:
          default: 0
          description: How many times it reopened after closing
          title: Reopen Count
          type: integer
        started_by:
          anyOf:
            - enum:
                - customer
                - user
                - digital_worker
                - system
              type: string
            - type: 'null'
          description: >-
            Who wrote the thread's first message: customer, user (a teammate),
            digital_worker (the AI's own outreach) or system; null when it can't
            be told
          title: Started By
        status:
          anyOf:
            - type: string
            - type: 'null'
          description: The workspace's own status name, such as NEEDS RESPONSE
          title: Status
        status_group:
          anyOf:
            - enum:
                - not_started
                - active
                - done
                - archived
              type: string
            - type: 'null'
          description: >-
            The status's group: not_started, active, done or archived, as a
            task's
          title: Status Group
        subject:
          anyOf:
            - type: string
            - type: 'null'
          description: The thread's title, else its first message's email subject
          title: Subject
        tags:
          items:
            $ref: '#/components/schemas/ConversationTag'
          title: Tags
          type: array
        updated_at:
          description: 'ISO 8601 UTC: its last change, else its creation'
          title: Updated At
          type: string
      required:
        - id
        - activity_id
        - created_at
        - updated_at
        - ai
      title: Conversation
      type: object
    ConversationAgent:
      properties:
        id:
          description: The AI's id in the workspace
          title: Id
          type: string
        name:
          title: Name
          type: string
      required:
        - id
        - name
      title: ConversationAgent
      type: object
    ConversationAi:
      properties:
        closed_by:
          anyOf:
            - enum:
                - ai_judged
                - ai_no_reply
                - quiet
                - person
              type: string
            - type: 'null'
          description: >-
            Why it closed: ai_judged (the AI replied and judged it resolved),
            ai_no_reply (the AI decided no reply was needed), quiet (our answer
            was last, then silence for the workspace's quiet period; also a
            conversation closed when its history was first loaded) or person (a
            person closed it, or their reply settled it). Null unless its status
            is Closed
          title: Closed By
        participated:
          description: >-
            Whether an AI wrote in the conversation: a digital worker's reply or
            outreach, or its draft a person sent. A notice that a person will
            reply is not taking part, and a reply a person wrote themselves is
            theirs, even when Stella suggested it
          title: Participated
          type: boolean
        resolution:
          anyOf:
            - enum:
                - resolved
                - engineering
                - person
                - none
              type: string
            - type: 'null'
          description: >-
            How it was resolved, once closed: resolved (an AI answered from
            knowledge or the account's data, with no person), engineering
            (handed to engineering), person (a person wrote, edited or approved
            a message) or none (nobody answered). No customer confirmation is
            recorded. Null unless its status is Closed
          title: Resolution
      required:
        - participated
      title: ConversationAi
      type: object
    ConversationAssignee:
      properties:
        id:
          description: The person's id
          title: Id
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        type:
          anyOf:
            - enum:
                - user
                - contact
                - vendor
                - digital_worker
              type: string
            - type: 'null'
          description: user (a teammate), as a rule
          title: Type
      required:
        - id
      title: ConversationAssignee
      type: object
    ConversationEngineeringIssue:
      properties:
        key:
          description: The issue's key in its tracker
          title: Key
          type: string
        state:
          anyOf:
            - enum:
                - open
                - started
                - shipped
                - closed_other
              type: string
            - type: 'null'
          description: >-
            open, started, shipped or closed_other, as last synced from the
            tracker
          title: State
        synced_at:
          anyOf:
            - type: string
            - type: 'null'
          description: 'ISO 8601 UTC: when its state was last synced'
          title: Synced At
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        tracker:
          anyOf:
            - enum:
                - linear
                - jira
                - statisfy
              type: string
            - type: 'null'
          description: 'Where the issue lives: statisfy (a task in Statisfy), linear or jira'
          title: Tracker
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
      required:
        - key
      title: ConversationEngineeringIssue
      type: object
    ConversationTag:
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
      required:
        - id
        - name
      title: ConversationTag
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.