> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replyful.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> REST API for building on top of Replyful

The Replyful REST API lets you read your support data programmatically — tickets, their conversations, every message, and your knowledge base Q\&As. The API is JSON over HTTPS, follows predictable conventions, and is designed to be curl-friendly so you can prototype from the terminal before writing a single line of code.

```bash theme={null}
curl https://api.replyful.com/v1/tickets?limit=1 \
  -H "Authorization: Bearer rfl_live_..."
```

## Data model

A **ticket** is the case container. Every ticket has exactly one **primary conversation** (the thread with the requester) and zero or more **side conversations** (isolated threads with other parties, e.g. a supplier). **Messages** belong to a conversation.

```
ticket ─┬─ conversation (primary) ─── messages
        └─ conversation (side)    ─── messages
```

## Base URL

```
https://api.replyful.com
```

HTTPS only — plain HTTP requests are rejected, not redirected.

## Quickstart

<Steps>
  <Step title="Create an API key">
    In the [dashboard](https://app.replyful.com), go to **Settings → Developers → API keys** and click **Create key**. Copy the token — it is shown once and never displayed again.
  </Step>

  <Step title="Make your first request">
    Replace `rfl_live_...` with your key and run:

    ```bash theme={null}
    curl https://api.replyful.com/v1/tickets?limit=1 \
      -H "Authorization: Bearer rfl_live_..."
    ```
  </Step>

  <Step title="Read the response">
    You get a list envelope with a single ticket:

    ```json theme={null}
    {
      "object": "list",
      "data": [
        {
          "id": "ti_...",
          "object": "ticket",
          "title": "Refund request",
          "status": "open",
          "requester": {
            "id": "con_...",
            "name": "Ada Lovelace",
            "email": { "email": "ada@example.com", "verified": true }
          },
          "tags": [],
          "topics": [],
          "conversations": [{ "id": "conv_...", "role": "primary" }],
          "createdAt": "2026-04-29T14:30:00Z",
          "updatedAt": "2026-04-29T14:32:00Z"
        }
      ],
      "hasMore": false,
      "nextCursor": null,
      "url": "/v1/tickets"
    }
    ```
  </Step>
</Steps>

## Conventions

Every endpoint in the API follows the same rules. Learn them once, apply them everywhere.

| Convention      | What to expect                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| **Auth**        | Bearer token in the `Authorization` header. See [Authentication](/api-reference/authentication).          |
| **Format**      | JSON request and response bodies. UTF-8.                                                                  |
| **Field names** | `camelCase` everywhere.                                                                                   |
| **Timestamps**  | ISO 8601 UTC strings, always with the trailing `Z` (e.g. `2026-04-29T14:32:00Z`).                         |
| **IDs**         | Strings, usually prefixed like `ti_...`, `conv_...`, `msg_...`, `con_...`. Treat them as opaque.          |
| **Pagination**  | Cursor-based. See [Pagination](/api-reference/pagination).                                                |
| **Errors**      | Status code is the source of truth. Body uses a consistent envelope. See [Errors](/api-reference/errors). |
| **Rate limits** | Documented headers on every response. See [Rate limits](/api-reference/rate-limits).                      |
| **Tracing**     | Every response includes a `Request-Id` header — quote it in support tickets.                              |

## What's available today

The API is in active development. Today, the following endpoints are live:

<Card title="GET /v1/tickets" icon="list" href="/api-reference/tickets/list" horizontal>
  List tickets with status filters, date ranges, sorting, and cursor pagination.
</Card>

<Card title="GET /v1/tickets/{id}" icon="ticket" href="/api-reference/tickets/retrieve" horizontal>
  Retrieve a single ticket with all of its conversations embedded.
</Card>

<Card title="GET /v1/conversations/{id}/messages" icon="messages" href="/api-reference/conversations/messages" horizontal>
  Page through a conversation's message thread, oldest first.
</Card>

<Card title="GET /v1/knowledge/qa" icon="book" href="/api-reference/knowledge/qa" horizontal>
  List your knowledge base Q\&As — questions, variations, and answers.
</Card>

More endpoints will land here as they ship. Field names, error codes, and ID prefixes are part of the public contract — they will not change without a major version bump.

## Need help?

Quote the `Request-Id` from any response when you contact support. We keep request traces for 90 days and can pull the exact context of a failing call from that ID.