List conversations | RealScout API documentation

List conversations Run in API Explorer

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://bump.sh/realscout/doc/realscout-api/mcp

Standard setup for AI tools providing an mcp.json file

{
  "RealScout API MCP server": {
    "url": "https://bump.sh/realscout/doc/realscout-api/mcp"
  }
}

GET /conversations

Bearer auth

The calling agent's message threads, most recent message first, each with its participants, when its latest message was sent, and how many messages others have sent since the agent last read it. A thread with no messages yet is left out, as in the agent app's inbox. Reading never marks a thread read.

Requires the conversations:read scope. Rate budget: 60 calls per 1 minute per credential (the list class).

Query parameters

archived boolean

true for the threads the agent has archived; omit or false for the inbox.
contact_id string

Only threads with this contact; an id that is none of the agent's contacts is an empty page.
cursor string

Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.
limit integer

Page size, 1 to 100.

Minimum value is 1, maximum value is 100. Default value is 25.

Responses

200 application/json

OK
Hide headers attributes Show headers attributes
- X-RateLimit-Limit integer
  
  Calls allowed in the current window.
- X-RateLimit-Remaining integer
  
  Calls left in the current window.
- X-RateLimit-Reset integer
  
  Epoch seconds at which the window resets.
Hide response attributes Show response attributes object
- data array[object] Required
  
  Hide data attributes Show data attributes object
  
  id string Required
  
  created_at string(date-time) | null Required
  
  last_message_at string(date-time) Required
  
  unread_count integer Required
  
  realscout_url string(uri) Required
  
  participants array[object] Required
  
  Hide participants attributes Show participants attributes object
  
  id string | null Required
  
  type string | null Required
  
  first_name string | null Required
  
  last_name string | null Required
  
  email string | null Required
- has_more boolean Required
- next_cursor string | null Required
  
  Send as cursor for the next page; null on the last one.
400 application/json

The request is invalid; field names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
401 application/json

Invalid or missing bearer token.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
403 application/json

The credential was not granted the scope this call requires.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
404 application/json

Not found, or not yours: the two are indistinguishable on purpose.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
429 application/json

Rate limit exceeded; Retry-After says when to try again.
Hide headers attribute Show headers attribute
- Retry-After integer
  
  Seconds until the budget refills.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
500 application/json

Something went wrong on our side.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.

GET /conversations

curl -H "Authorization: Bearer rs_agent_..." "https://www.realscout.com/api/agent/v1/conversations?limit=25"

Response examples (200)

{
  "data": [
    {
      "id": "Q29udmVyc2F0aW9uLTQy",
      "created_at": "2026-08-06T07:06:40Z",
      "last_message_at": "2026-08-19T02:11:00Z",
      "unread_count": 2,
      "realscout_url": "https://www.realscout.com/agent/conversations/Q29udmVyc2F0aW9uLTQy",
      "participants": [
        {
          "id": "QWdlbnQtNw==",
          "type": "Agent",
          "first_name": "Dana",
          "last_name": "Agent",
          "email": "dana@example.com"
        },
        {
          "id": "VXNlci0xMjM=",
          "type": "User",
          "first_name": "Eleanor",
          "last_name": "Nguyen",
          "email": "eleanor@example.com"
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "bGlzdF9jb252ZXJzYXRpb25zfFd5SXlNREkyTFRBNExUSXlJREE1T2pBd09qQXdJaXcwTWwwPQ"
}

Response examples (400)

{
  "error": {
    "code": "invalid_request",
    "message": "limit must be an integer.",
    "field": "limit",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (401)

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing credentials.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (403)

{
  "error": {
    "code": "missing_scope",
    "message": "This call requires the conversations:read scope, which this credential was not granted.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (404)

{
  "error": {
    "code": "not_found",
    "message": "No endpoint at GET /api/agent/v1/conversations.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (429)

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (500)

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}