Conversations API

Conversations are chat sessions between a user and a REPLR. Each conversation holds an ordered sequence of messages and maintains its own context window so the REPLR can recall what was said earlier in the thread.

Base URL

https://api.replr.ai/v1

POST/v1/conversationsAuth Required

Create a new conversation with a REPLR. Optionally provide a title; if omitted the REPLR will auto-generate one after the first exchange.

Request Body

Name	Type	Required	Description
`replr_id`	string	Required	ID of the REPLR to start a conversation with.
`title`	string	Optional	Optional display title. Auto-generated from the first message if not provided.

Response

{
  "id": "conv_a1b2c3d4e5f6",
  "replr_id": "replr_9x8y7z6w5v4u",
  "title": null,
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T14:22:00Z",
  "message_count": 0
}

Examples

curl -X POST https://api.replr.ai/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "replr_id": "replr_9x8y7z6w5v4u",
    "title": "Onboarding chat"
  }'

GET/v1/conversationsAuth Required

List conversations for the authenticated user. Filter by REPLR and paginate through results.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Optional	Filter conversations to a specific REPLR.
`limit`	integer	Optional	Maximum number of results to return (1-100). Default: 20.
`offset`	integer	Optional	Number of results to skip for pagination. Default: 0.

Response

{
  "data": [
    {
      "id": "conv_a1b2c3d4e5f6",
      "replr_id": "replr_9x8y7z6w5v4u",
      "title": "Onboarding chat",
      "created_at": "2026-03-09T14:22:00Z",
      "updated_at": "2026-03-09T14:35:12Z",
      "message_count": 8
    },
    {
      "id": "conv_f6e5d4c3b2a1",
      "replr_id": "replr_9x8y7z6w5v4u",
      "title": "Product questions",
      "created_at": "2026-03-08T09:10:00Z",
      "updated_at": "2026-03-08T09:48:33Z",
      "message_count": 14
    }
  ],
  "has_more": true,
  "total": 37
}

Examples

curl "https://api.replr.ai/v1/conversations?replr_id=replr_9x8y7z6w5v4u&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/conversations/:idAuth Required

Retrieve a single conversation, including the most recent messages.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Response

{
  "id": "conv_a1b2c3d4e5f6",
  "replr_id": "replr_9x8y7z6w5v4u",
  "title": "Onboarding chat",
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T14:35:12Z",
  "message_count": 8,
  "messages": [
    {
      "id": "msg_t1u2v3w4x5y6",
      "conversation_id": "conv_a1b2c3d4e5f6",
      "role": "user",
      "content": "Hey, how do I get started?",
      "created_at": "2026-03-09T14:22:05Z"
    },
    {
      "id": "msg_z6y5x4w3v2u1",
      "conversation_id": "conv_a1b2c3d4e5f6",
      "role": "assistant",
      "content": "Welcome! I can walk you through the basics. What are you looking to build?",
      "created_at": "2026-03-09T14:22:07Z"
    }
  ]
}

Examples

curl "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/v1/conversations/:idAuth Required

Permanently delete a conversation and all of its messages. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID to delete.

Response

{
  "id": "conv_a1b2c3d4e5f6",
  "deleted": true
}

Examples

curl -X DELETE "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/conversations/:id/messagesAuth Required

Retrieve the message history for a conversation. Supports cursor-based pagination for efficient scrollback.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.
`limit`	integer	Optional	Maximum number of results to return (1-100). Default: 20.
`offset`	integer	Optional	Number of results to skip for pagination. Default: 0.
`before`	string	Optional	Message ID cursor. Returns messages created before this message, newest first.

Response

{
  "data": [
    {
      "id": "msg_t1u2v3w4x5y6",
      "conversation_id": "conv_a1b2c3d4e5f6",
      "role": "user",
      "content": "Hey, how do I get started?",
      "created_at": "2026-03-09T14:22:05Z"
    },
    {
      "id": "msg_z6y5x4w3v2u1",
      "conversation_id": "conv_a1b2c3d4e5f6",
      "role": "assistant",
      "content": "Welcome! I can walk you through the basics. What are you looking to build?",
      "created_at": "2026-03-09T14:22:07Z"
    }
  ],
  "has_more": true
}

Examples

curl "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6/messages?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/v1/conversations/:id/messagesAuth Required

Send a message and receive the REPLR's response synchronously. The request blocks until the full response is generated.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.
`role`	string	Optional	Sender role. Must be "user". Default: "user".

Response

{
  "user_message": {
    "id": "msg_a1b2c3d4e5f6",
    "conversation_id": "conv_a1b2c3d4e5f6",
    "role": "user",
    "content": "What can you help me with?",
    "created_at": "2026-03-09T14:30:00Z"
  },
  "assistant_message": {
    "id": "msg_g7h8i9j0k1l2",
    "conversation_id": "conv_a1b2c3d4e5f6",
    "role": "assistant",
    "content": "I can help you with onboarding, product questions, troubleshooting, and more. What would you like to dive into?",
    "created_at": "2026-03-09T14:30:02Z"
  }
}

Examples

curl -X POST "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "What can you help me with?"}'

POST/v1/conversations/:id/messages/streamAuth Required

Send a message and receive the REPLR's response as a Server-Sent Events (SSE) stream. Ideal for real-time UIs that display tokens as they arrive.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.

Response

// Content-Type: text/event-stream

event: delta
data: {"content": "I can "}

event: delta
data: {"content": "help you "}

event: delta
data: {"content": "with onboarding, "}

event: delta
data: {"content": "product questions, and more."}

event: done
data: {"message_id": "msg_g7h8i9j0k1l2"}

Examples

curl -N -X POST "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6/messages/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "What can you help me with?"}'

GET/v1/conversations/searchAuth Required

Full-text search across all conversations for the authenticated user. Returns matching messages with their conversation context.

Path Parameters

Name	Type	Required	Description
`q`	string	Required	Search query string.
`limit`	integer	Optional	Maximum number of matching messages to return (1-100). Default: 20.

Response

{
  "data": [
    {
      "message": {
        "id": "msg_t1u2v3w4x5y6",
        "conversation_id": "conv_a1b2c3d4e5f6",
        "role": "user",
        "content": "How do I configure webhooks?",
        "created_at": "2026-03-09T14:22:05Z"
      },
      "conversation": {
        "id": "conv_a1b2c3d4e5f6",
        "title": "Onboarding chat"
      },
      "highlight": "How do I configure <mark>webhooks</mark>?"
    }
  ],
  "has_more": false,
  "total": 1
}

Examples

curl "https://api.replr.ai/v1/conversations/search?q=webhooks&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

SSE Streaming Format

The streaming endpoint returns a text/event-stream response using the Server-Sent Events protocol. Each event has a named type and a JSON payload on the data: line.

Event Type	Payload	Description
`delta`	{ "content": "..." }	A chunk of the assistant's response. Concatenate all delta payloads to build the full message.
`done`	{ "message_id": "..." }	Signals the response is complete. Contains the final message ID for the stored assistant message.
`error`	{ "code": "...", "message": "..." }	An error occurred during generation. The stream will close after this event. Inspect `code` for the error type (e.g. `rate_limited`, `context_length_exceeded`).

Tip: Always listen for the done event to confirm the stream has completed. If the connection drops before a done or error event, treat it as a network failure and retry with the same message.

Conversations API

Base URL

https://api.replr.ai/v1

POST/v1/conversationsAuth Required

Create a new conversation with a REPLR. Optionally provide a title; if omitted the REPLR will auto-generate one after the first exchange.

Request Body

Name	Type	Required	Description
`replr_id`	string	Required	ID of the REPLR to start a conversation with.
`title`	string	Optional	Optional display title. Auto-generated from the first message if not provided.

Response

{
  "id": "conv_a1b2c3d4e5f6",
  "replr_id": "replr_9x8y7z6w5v4u",
  "title": null,
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T14:22:00Z",
  "message_count": 0
}

Examples

curl -X POST https://api.replr.ai/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "replr_id": "replr_9x8y7z6w5v4u",
    "title": "Onboarding chat"
  }'

GET/v1/conversationsAuth Required

List conversations for the authenticated user. Filter by REPLR and paginate through results.

Path Parameters

Name	Type	Required	Description
`replr_id`	string	Optional	Filter conversations to a specific REPLR.
`limit`	integer	Optional	Maximum number of results to return (1-100). Default: 20.
`offset`	integer	Optional	Number of results to skip for pagination. Default: 0.

Response

{
  "data": [
    {
      "id": "conv_a1b2c3d4e5f6",
      "replr_id": "replr_9x8y7z6w5v4u",
      "title": "Onboarding chat",
      "created_at": "2026-03-09T14:22:00Z",
      "updated_at": "2026-03-09T14:35:12Z",
      "message_count": 8
    },
    {
      "id": "conv_f6e5d4c3b2a1",
      "replr_id": "replr_9x8y7z6w5v4u",
      "title": "Product questions",
      "created_at": "2026-03-08T09:10:00Z",
      "updated_at": "2026-03-08T09:48:33Z",
      "message_count": 14
    }
  ],
  "has_more": true,
  "total": 37
}

Examples

curl "https://api.replr.ai/v1/conversations?replr_id=replr_9x8y7z6w5v4u&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/conversations/:idAuth Required

Retrieve a single conversation, including the most recent messages.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Response

{
  "id": "conv_a1b2c3d4e5f6",
  "replr_id": "replr_9x8y7z6w5v4u",
  "title": "Onboarding chat",
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T14:35:12Z",
  "message_count": 8,
  "messages": [
    {
      "id": "msg_t1u2v3w4x5y6",
      "conversation_id": "conv_a1b2c3d4e5f6",
      "role": "user",
      "content": "Hey, how do I get started?",
      "created_at": "2026-03-09T14:22:05Z"
    },
    {
      "id": "msg_z6y5x4w3v2u1",
      "conversation_id": "conv_a1b2c3d4e5f6",
      "role": "assistant",
      "content": "Welcome! I can walk you through the basics. What are you looking to build?",
      "created_at": "2026-03-09T14:22:07Z"
    }
  ]
}

Examples

curl "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/v1/conversations/:idAuth Required

Permanently delete a conversation and all of its messages. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID to delete.

Response

{
  "id": "conv_a1b2c3d4e5f6",
  "deleted": true
}

Examples

curl -X DELETE "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/conversations/:id/messagesAuth Required

Retrieve the message history for a conversation. Supports cursor-based pagination for efficient scrollback.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.
`limit`	integer	Optional	Maximum number of results to return (1-100). Default: 20.
`offset`	integer	Optional	Number of results to skip for pagination. Default: 0.
`before`	string	Optional	Message ID cursor. Returns messages created before this message, newest first.

Response

{
  "data": [
    {
      "id": "msg_t1u2v3w4x5y6",
      "conversation_id": "conv_a1b2c3d4e5f6",
      "role": "user",
      "content": "Hey, how do I get started?",
      "created_at": "2026-03-09T14:22:05Z"
    },
    {
      "id": "msg_z6y5x4w3v2u1",
      "conversation_id": "conv_a1b2c3d4e5f6",
      "role": "assistant",
      "content": "Welcome! I can walk you through the basics. What are you looking to build?",
      "created_at": "2026-03-09T14:22:07Z"
    }
  ],
  "has_more": true
}

Examples

curl "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6/messages?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/v1/conversations/:id/messagesAuth Required

Send a message and receive the REPLR's response synchronously. The request blocks until the full response is generated.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.
`role`	string	Optional	Sender role. Must be "user". Default: "user".

Response

{
  "user_message": {
    "id": "msg_a1b2c3d4e5f6",
    "conversation_id": "conv_a1b2c3d4e5f6",
    "role": "user",
    "content": "What can you help me with?",
    "created_at": "2026-03-09T14:30:00Z"
  },
  "assistant_message": {
    "id": "msg_g7h8i9j0k1l2",
    "conversation_id": "conv_a1b2c3d4e5f6",
    "role": "assistant",
    "content": "I can help you with onboarding, product questions, troubleshooting, and more. What would you like to dive into?",
    "created_at": "2026-03-09T14:30:02Z"
  }
}

Examples

curl -X POST "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "What can you help me with?"}'

POST/v1/conversations/:id/messages/streamAuth Required

Send a message and receive the REPLR's response as a Server-Sent Events (SSE) stream. Ideal for real-time UIs that display tokens as they arrive.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.

Response

// Content-Type: text/event-stream

event: delta
data: {"content": "I can "}

event: delta
data: {"content": "help you "}

event: delta
data: {"content": "with onboarding, "}

event: delta
data: {"content": "product questions, and more."}

event: done
data: {"message_id": "msg_g7h8i9j0k1l2"}

Examples

curl -N -X POST "https://api.replr.ai/v1/conversations/conv_a1b2c3d4e5f6/messages/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "What can you help me with?"}'

GET/v1/conversations/searchAuth Required

Full-text search across all conversations for the authenticated user. Returns matching messages with their conversation context.

Path Parameters

Name	Type	Required	Description
`q`	string	Required	Search query string.
`limit`	integer	Optional	Maximum number of matching messages to return (1-100). Default: 20.

Response

{
  "data": [
    {
      "message": {
        "id": "msg_t1u2v3w4x5y6",
        "conversation_id": "conv_a1b2c3d4e5f6",
        "role": "user",
        "content": "How do I configure webhooks?",
        "created_at": "2026-03-09T14:22:05Z"
      },
      "conversation": {
        "id": "conv_a1b2c3d4e5f6",
        "title": "Onboarding chat"
      },
      "highlight": "How do I configure <mark>webhooks</mark>?"
    }
  ],
  "has_more": false,
  "total": 1
}

Examples

curl "https://api.replr.ai/v1/conversations/search?q=webhooks&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

SSE Streaming Format

The streaming endpoint returns a text/event-stream response using the Server-Sent Events protocol. Each event has a named type and a JSON payload on the data: line.

Event Type	Payload	Description
`delta`	{ "content": "..." }	A chunk of the assistant's response. Concatenate all delta payloads to build the full message.
`done`	{ "message_id": "..." }	Signals the response is complete. Contains the final message ID for the stored assistant message.
`error`	{ "code": "...", "message": "..." }	An error occurred during generation. The stream will close after this event. Inspect `code` for the error type (e.g. `rate_limited`, `context_length_exceeded`).

Tip: Always listen for the done event to confirm the stream has completed. If the connection drops before a done or error event, treat it as a network failure and retry with the same message.