Retrieve messages from a conversation

GET

/conversations/{conversationId}/messages

curl --request GET \
  --url 'https://api.siteassist.io/v2/conversations/123e4567-e89b-12d3-a456-426614174000/messages?limit=50&offset=0&role=user&status=complete' \
  --header 'Authorization: Bearer <token>'

• Production server

Retrieve messages from a conversation, ordered chronologically from oldest to newest. Supports pagination and filtering by role or status. Only the conversation owner can access their messages.

Authorizations

• bearerAuth

Parameters

Path Parameters

conversationId

required

The unique identifier of the conversation to retrieve messages from

string format: uuid

Example

123e4567-e89b-12d3-a456-426614174000

Query Parameters

limit

Maximum number of messages to return (default: all messages, max: 1000)

integer

>= 1 <= 1000

Example

50

offset

Number of messages to skip for pagination (default: 0)

integer

nullable

Example

0

role

Filter messages by role (user, assistant, or human_agent)

string

Allowed values: user assistant human_agent

Example

assistant

status

Filter messages by status (complete, streaming, or error)

string

Allowed values: complete streaming error

Example

complete

Responses

200

Successfully retrieved all messages from the conversation. Messages are returned in chronological order (oldest first) and include all metadata such as creation time, role, status, and feedback information.

Media typeapplication/json

Response containing the list of messages from the conversation, ordered chronologically from oldest to newest

object

object

string

default: list

Allowed values: list

data

required

Array<object>

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

string

number

number

boolean

boolean

unknown

nullable

object

object

key

additional properties

nullable

Array

Array

unknown

nullable

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",
  "data": [
    {
      "object": "message",
      "role": "assistant",
      "parts": [
        {
          "type": "text",
          "text": "Hello, world!"
        }
      ],
      "status": "streaming",
      "feedback": "like",
      "humanAgent": null
    }
  ]
}

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

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

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

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

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

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

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

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

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

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

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
    }
  }
}