PIpipeshub-ai
Conversations

List all conversations

Changed on

Retrieve paginated conversations for the authenticated user.

Overview:

Use the optional source query parameter to choose which list to return: owned — only conversations you own (userId matches the current user). shared — conversations where you have recipient access (isShared and your user appears in sharedWith), without the owner-only branch. Defaults to owned when omitted. Each call returns one list; call twice if you need both.

Filtering:

  • Only non-archived conversations are returned by default
  • Use /conversations/show/archives for archived conversations

Sorting:

Conversations are sorted by last activity timestamp (most recent first) by default. With source=owned, conversations the caller pinned (PATCH /conversations/{conversationId}/pin) come first, in the same order, whatever sortBy is. source=shared is never pinned-first.

Query parameters not listed here are ignored, not refused.

get/conversations

Request

  • Base URL
    https://app.pipeshub.com/api/v1
  • URL
    https://app.pipeshub.com/api/v1/conversations
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: /api/v1/oauth2/authorize
      Client credentials
      Token URL: /api/v1/oauth2/token scopes: conversation:read

Query parameters

source'owned' | 'shared'

owned — owner list (userId filter only). shared — explicit share grant list (isShared + sharedWith). Includes agent conversations shared with the caller; those rows carry agentKey. Defaults to owned when omitted.

pagenumber

Page number (1-based). Defaults to 1. The validator accepts any number, so a fraction such as 1.5 is not refused; it is truncated (1.5 reads as page 1).

limitinteger

Page size. Defaults to 10; values above 100, and fractions, are refused (400 VALIDATION_ERROR).

sortBy'createdAt' | 'lastActivityAt' | 'title'

Sort field. Invalid values fall back to lastActivityAt.

sortOrder'asc' | 'desc'

Sort direction. Defaults to desc unless set to asc.

conversationIdstring

When set, restricts results to that conversation ID (if visible under the chosen source).

searchstring

Case-insensitive match on title and message content (max 1000 characters).

startDatestring date-time

Filter by createdAt ≥ this instant. Must be a full ISO 8601 date-time with Z or a numeric offset; a bare date is refused.

endDatestring date-time

Filter by createdAt ≤ this instant. Must be a full ISO 8601 date-time with Z or a numeric offset; a bare date is refused.

shared'true' | 'false' | '1' | '0'

When set, filters by isShared. Accepts exactly true, false, 1 or 0.

projectIdstring

Restrict results to a single project. Pass a project's id to list conversations linked to that project (visible to the caller — owner, member, or org-visible project with projectVisibility: project), or the literal string unassigned to list conversations with no projectId.

Response

List of conversations for the requested source

source'owned' | 'shared' required

Echoes the requested source query value.

Changes

  • dbb5e203b445Revision changes
    • breaking

      the query request parameter shared was restricted to a list of enum values

    • breaking

      for the query request parameter limit, default value 10 was added

    • breaking

      added the pattern ^(unassigned|[0-9a-fA-F]{24})$ to the query request parameter projectId

    • breaking

      added the pattern ^[0-9a-fA-F]{24}$ to the query request parameter conversationId

    • breaking

      added the pattern ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$ to the query request parameter endDate

    • breaking

      added the pattern ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$ to the query request parameter startDate

    • warning

      for the query request parameter search, the maxLength was set to 1000

    • warning

      for the query request parameter limit, the max was set to 100.00

    • info

      added the new enum value 0 to the query request parameter shared

    • info

      added the new enum value 1 to the query request parameter shared

    • info

      added the new enum value false to the query request parameter shared

    • info

      added the new enum value true to the query request parameter shared

    • info

      for the query request parameter page, the type was generalized from integer to number

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property //// to the response with the status

  • fc76aa045994Revision changes
    • info

      added the optional property // to the response with the status