Skip to main content
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
CapabilityEndpoint(s)Description
List & searchGET /conversationsRetrieve the sidebar-style list with optional q param for title/preview search
InspectGET /conversations/{conversationId}, GET /conversations/{conversationId}/messagesFetch metadata plus paginated message history
Update metadataPATCH /conversations/{conversationId}Rename, pin, or retag a chat
LifecyclePOST /conversations/{conversationId}/archive, POST /conversations/{conversationId}/restore, DELETE /conversations/{conversationId}Archive, unarchive, or soft-delete a thread
FeedbackPOST /messages/{messageId}/feedbackSubmit 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.