Ferndesk

Assistant conversations

List assistant conversations

Returns AI assistant conversations, newest first, cursor-paginated, with feedback, coverage, and date filters.

When a feedback or coverage filter is active, matches are gathered across the underlying windows so a page is never short-changed by filtered-out rows. To keep a single request bounded it scans at most 10 windows; if that ceiling is hit before a full page is collected, has_more is true and next_cursor resumes from where the scan stopped, so following the cursor continues the scan without skipping matches.

Response fields are a deliberate public contract: internal metadata, references, and raw message structures are never included in the list shape. Requires the conversations:read scope.

Required scope: conversations:read

GET /assistant/conversations

List assistant conversations

curl --request GET \
  --url 'https://api.ferndesk.com/v1/assistant/conversations' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "results": [
    {
      "id": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "status": "<string>",
      "source": "help",
      "pageUrl": "<string>",
      "user": {},
      "summary": "<string>",
      "coverage": "covered",
      "feedback": "positive",
      "escalated": true,
      "messageCount": 1
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

Cursor-paginated conversations

Authorizations

  • Authorization string required header

    All requests require a Bearer token in the Authorization header. API keys are prefixed with fdsk_ and should be kept secret. You can generate and manage keys from the Developer settings page.

    Keys can be restricted to any subset of these scopes (each endpoint lists the scope it requires via x-required-scopes):

    • content:read: Read and search help center articles, collections, sections, and translations
    • content:write: Create and edit article drafts, users, tasks; move articles and collections
    • content:publish: Publish, unpublish, restore, and trash content (make changes live)
    • analytics:read: Read help center reporting, analytics, and article feedback
    • conversations:read: Read AI assistant conversations and transcripts
    • webhooks:manage: Create and manage outbound webhook subscriptions

    Granting content:write or content:publish implies content:read. Keys minted before scoping have null scopes = full access (legacy mode).

Query Parameters

  • coverage string enum
  • end_date string

    ISO date upper bound.

  • feedback string enum
  • page_size integer

    Number of items to return per page (1-100). Example: 20

  • start_cursor string

    Opaque pagination cursor. Pass the next_cursor from a previous response to fetch the next page. Example: eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ

  • start_date string

    ISO date lower bound.

Response

application/json
  • results[] object array

    Items in this page. Assistant conversation summary — a deliberate public contract, not the raw row.

    + Show Child Attributes
    • id string
    • createdAt string

      ISO 8601 timestamp in UTC.

    • updatedAt string

      ISO 8601 timestamp in UTC.

    • status string

      Conversation lifecycle status.

    • source string enum | null

      Where the conversation originated: the help center (help) or the embedded widget (widget).

    • pageUrl string | null

      The page the end user was on when the conversation started, if captured.

    • user anyOf

      The identified help center user for this conversation, or null when the end user was anonymous.

      + Show Child Attributes
      • anyOf options 2 variants anyOf

        One or more options can apply.

        + Show Child Attributes
        • option 1 object
          + Show Child Attributes
          • id string

            Ferndesk help center user ID (hcusr_...).

          • name string | null

            Help center user display name.

        • option 2 null
    • summary string | null

      AI-generated one-line summary, if available.

    • coverage string enum | null

      How well the help center covered the question.

    • feedback string enum | null

      End-user thumbs feedback on the conversation, or null if none was left.

    • escalated boolean

      Whether the conversation was escalated to a human.

    • messageCount integer

      Number of end-user messages in the conversation.

  • has_more boolean

    Whether more items are available after this page.

  • next_cursor string | null

    Cursor to pass as start_cursor for the next page, or null on the last page.