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

# Conversations API

> Authenticated history, metadata, and lifecycle management for user conversations.

The `/api/v1/user/*` router powers the in-app conversation list, individual
threads, and lifecycle actions such as pinning, archiving, restoring, or
deleting chats. All endpoints support **both Auth0 JWT and device-based authentication**,
enabling seamless access for both registered users and guest users during trial flows.

### Authentication Methods

All conversation endpoints support **two authentication options**:

1. **Auth0 JWT** (Registered users)
   * Header: `Authorization: Bearer <token>`
   * Standard authenticated flow for logged-in users

2. **Device-based** (Guest users)
   * Headers: `x-device-id`, `x-user-id` (optional), `x-platform`
   * Same authentication as chat API
   * Enables conversation management during free trial/guest sessions

### Conversation Metadata

Each conversation now includes rich metadata to support analytics and better UX:

* **`type`**: `'chat'` or `'second_opinion'` - Differentiates main chat from second opinion feature
* **`inputType`**: `'text'`, `'file'`, or `'voice'` - How the conversation was initiated (tracks user engagement patterns)
* **`prepromptKey`**: The pre-prompt used when creating the conversation (enables pre-prompt analytics)

These fields are automatically populated when conversations are created and are available in both list and detail responses.

### Quick facts

* Base path: `/api/v1/user`
* All responses use the shared `{ success, data, meta }` envelope
* Pagination follows `limit/offset` semantics with a `hasMore` cursor hint where applicable
* Conversation IDs are MongoDB ObjectIds (24 hex characters)
* Both authentication methods work identically - choose based on your use case

| Capability      | Endpoint(s)                                                                                                                                                                                                              | Description                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| List & search   | [`GET /conversations`](./conversations/list)                                                                                                                                                                             | Retrieve the sidebar-style list with optional `q` param for title/preview search |
| Inspect         | [`GET /conversations/{conversationId}`](./conversations/details), [`GET /conversations/{conversationId}/messages`](./conversations/messages)                                                                             | Fetch metadata plus paginated message history                                    |
| Update metadata | [`PATCH /conversations/{conversationId}`](./conversations/update)                                                                                                                                                        | Rename, pin, or retag a chat                                                     |
| Lifecycle       | [`POST /conversations/{conversationId}/archive`](./conversations/archive), [`POST /conversations/{conversationId}/restore`](./conversations/restore), [`DELETE /conversations/{conversationId}`](./conversations/delete) | Archive, unarchive, or soft-delete a thread                                      |
| Feedback        | [`POST /messages/{messageId}/feedback`](./conversations/message-feedback)                                                                                                                                                | Submit like/dislike rating and optional text feedback                            |

### Using the API Playground

In the "Try it" section on each endpoint page:

1. **Select your authentication method** from the security dropdown
2. **For Auth0 JWT**: Enter your bearer token in the Authorization field
3. **For Device-based**: The playground will show fields for `x-device-id`, `x-user-id`, and `x-platform`

The API will automatically detect which authentication method you're using based on the headers present in your request.

Use the endpoint pages above (and the OpenAPI controls alongside them) to try
requests directly from the docs site.