Skip to content
SiteAssistSiteAssistSiteAssist

List conversations

GET
/conversations
curl --request GET \
  --url 'https://api.siteassist.io/v2/conversations?limit=10&offset=0&status=open&orderBy=id&orderDir=asc' \
  --header 'Authorization: Bearer <token>'

Retrieve a paginated list of conversations for the authenticated visitor within the current project. Supports filtering, ordering, and pagination.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
number
default: 10 >= 1 <= 100
offset
number
0 nullable
status
string
Allowed values: open closed
orderBy
string
default: lastInteractionAt
Allowed values: id createdAt updatedAt lastInteractionAt status closedAt isHumanHandled title
orderDir
string
default: desc
Allowed values: asc desc

Responses

Section titled “Responses”

200

Section titled “200”

Successfully retrieved conversations list

Media typeapplication/json

A list response object including total count and an array of conversation summaries.

object
object
string
default: list
Allowed values: list
total
required
number
limit
required
number
offset
required
number
data
required
Array<object>
object
object

The type of object returned, always ‘conversation’

string
default: conversation
Allowed values: conversation
id
required
string format: uuid
createdAt
required
string
updatedAt
required
string
status
required
string
Allowed values: open closed
closedAt
required
string
nullable
closeReason
required
string
nullable
lastInteractionAt
required
string
isHumanHandled

Whether this conversation is being handled by a human agent instead of AI

boolean
humanAgent

Information about the human agent assigned to this conversation, if any

object
name
required
string
nullable
image
required
string
nullable
title
required
string
nullable
lastMessage
object
object
string
default: message
Allowed values: message
id
required
string format: uuid
createdAt
required
string
chatId
required
string format: uuid
role
required
string
Allowed values: assistant human_agent user
parts
required

The parts of the message.

Array
status
required
string
nullable
Allowed values: streaming complete error
error
required
string
nullable
feedback
required
string
nullable
Allowed values: like dislike
feedbackAt
required
string
nullable
metadata
required
Any of:
string
humanAgent
object
name
required
string
nullable
image
required
string
nullable
pageUrl
required
string
nullable
pageTitle
required
string
nullable
textSelection
required
string
nullable
Example
{
  "object": "list",
  "total": 1,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "object": "conversation",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "status": "open",
      "closedAt": null,
      "closeReason": null,
      "lastInteractionAt": "2024-01-15T10:30:00.000Z",
      "isHumanHandled": false,
      "humanAgent": null,
      "lastMessage": null
    }
  ]
}

400

Section titled “400”

Bad Request - The request body or parameters are invalid

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Invalid request body. Content is required.",
    "code": "INVALID_REQUEST_BODY",
    "details": {
      "field": "content"
    }
  }
}

401

Section titled “401”

Unauthorized - Authentication token is missing or invalid

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Authentication required",
    "code": "UNAUTHORIZED"
  }
}

402

Section titled “402”

Payment Required - A higher pricing plan is required to access the resource

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "A higher pricing plan is required to access this feature",
    "code": "PAYMENT_REQUIRED",
    "details": {
      "currentPlan": "free",
      "requiredPlan": "pro",
      "feature": "advanced_ai_models"
    }
  }
}

403

Section titled “403”

Forbidden - Access denied to the requested resource

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Access denied to this conversation",
    "code": "FORBIDDEN"
  }
}

404

Section titled “404”

Not Found - The requested resource was not found

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Conversation not found!",
    "code": "CONVERSATION_NOT_FOUND",
    "details": {
      "conversationId": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

409

Section titled “409”

Conflict - The request could not be completed due to a conflict

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Resource already exists",
    "code": "CONFLICT",
    "details": {
      "resource": "conversation",
      "conflictingField": "id"
    }
  }
}

422

Section titled “422”

Unprocessable Entity - The request was well-formed but contains semantic errors

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": {
      "field": "content",
      "reason": "Content exceeds maximum length of 10000 characters"
    }
  }
}

429

Section titled “429”

Too Many Requests - Rate limit exceeded or quota reached

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "retryAfter": 60
    }
  }
}

500

Section titled “500”

Internal Server Error - An unexpected error occurred

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "An internal server error occurred",
    "code": "INTERNAL_SERVER_ERROR"
  }
}

502

Section titled “502”

Bad Gateway - The server received an invalid response from an upstream server

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Service temporarily unavailable",
    "code": "BAD_GATEWAY",
    "details": {
      "service": "ai_model_service"
    }
  }
}

503

Section titled “503”

Service Unavailable - The server is temporarily unable to handle the request

Media typeapplication/json
object
error
required
object
message
required

Human-readable error message describing what went wrong

string
code

Machine-readable error code for programmatic handling

string
details

Additional error details and context

object
key
additional properties
nullable
Example
{
  "error": {
    "message": "Service temporarily unavailable",
    "code": "SERVICE_UNAVAILABLE",
    "details": {
      "retryAfter": 30
    }
  }
}