> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve user's favorite dialogues
> Returns history records marked as favorites by the authenticated user. Uses the same HistoryRecord response shape as /histories. Results are trimmed (inputs/outputs to 200 chars, tool responses to 80 chars). Limited to 1000 records.
## OpenAPI
````yaml /mdx/api-reference/runtime/runtime-api.json post /api/user/favorites
openapi: 3.0.0
info:
title: Pria Runtime API
version: 2.0.1
description: >-
Pria API Documentation Praxis's developer platform is a core part of our
mission to empower organizations to grow better. Our APIs are designed to
enable teams of any shape or size to build robust integrations that help
them customize and get the most value out of Pria. All Pria APIs are built
using REST conventions and designed to have a predictable URL structure.
They use many standard HTTP features, including methods (POST,
GET, PUT, DELETE) and error response codes.
All API calls are
made under https://hiimpria.ai/api and all responses return standard JSON.
In these docs, you'll find lists of all available endpoints for a given API,
along with interactive code blocks for building requests. For walkthroughs
of basic usage for these APIs, check out the API guides.
servers:
- url: https://pria.praxislxp.com
description: Pria API Server
security: []
tags:
- name: Authentication
description: User authentication, registration, and password management (/api/auth)
- name: OAuth
description: OAuth authentication providers - Google, GitHub, SSO (/api/auth/oauth)
- name: User
description: User profile management and account operations (/api/user)
- name: User Institutions
description: User institution memberships and switching (/api/user/institution)
- name: User Tools
description: Available tools for authenticated users (/api/user/tools)
- name: Institutions
description: Institution settings and configuration (/api/user/institution)
- name: Conversation
description: AI conversation and Q&A endpoints (/api/ai)
- name: Realtime
description: Real-time voice AI and WebRTC sessions (/api/ai/rt)
- name: Assistant
description: AI assistant configuration and management (/api/user/assistant)
- name: History
description: Conversation history and favorites (/api/user/history)
- name: RAG
description: >-
Document upload, embedding, and retrieval-augmented generation
(/api/user/files, /api/user/rag)
- name: Setting
description: Instance variables and settings management (/api/user/setting)
- name: Branding
description: Digital twin branding and customization (/api/agent/branding)
- name: Agent
description: Agent engagement and session management (/api/agent)
- name: SDK Launch
description: >-
SDK launch token signing and verification for secure iframe embedding
(/api/auth/sdk-sign, /api/auth/sdk-verify)
- name: Testing
description: Health checks, diagnostics, and test endpoints (/api/test)
- name: Admin Accounts
description: Account management for super admins (/api/admin/account)
- name: Admin Institutions
description: Institution management for admins (/api/admin/institution)
- name: Admin Users
description: User management for admins (/api/admin/user)
- name: Admin Entitlements
description: >-
User-institution relationships and permissions
(/api/admin/userInstitution)
- name: Admin Sessions
description: Session management for admins (/api/admin/session)
- name: Admin Histories
description: Conversation history management and analytics (/api/admin/history)
- name: Admin Assistants
description: AI assistant management for admins (/api/admin/assistant)
- name: Admin Questions
description: Institution question and prompt management (/api/admin/question)
- name: Admin Tools
description: Tool configuration management (/api/admin/tool)
- name: Admin AI Models
description: AI model configuration (/api/admin/aimodel)
- name: Admin MCP Servers
description: Model Context Protocol server management (/api/admin/mcpserver)
- name: Admin Feedbacks
description: User feedback management (/api/admin/feedback)
- name: Admin Uploads
description: Upload management (/api/admin/upload)
- name: Admin Charts
description: Analytics and visualization chart management (/api/admin/chart)
- name: Audio Notes
description: Capture and ingest spoken notes into the personal vault
- name: Memory
description: User-facing memory parameters (personal + shared instance memory).
- name: My Data
description: >-
GDPR controls — personal-scope counts, async ZIP-by-email export, and
scoped soft-delete. Every endpoint pins `user = req.user._id` AND
`institution: null`; institution-scoped data is governed by the
institution's own retention policy and never reached from here.
- name: Questions
description: >-
User-facing read of the onboarding question bank used by the "create a
digital twin" wizard.
- name: Transcription
description: >-
One-shot speech-to-text for in-place dictation. Audio blob in, transcript
out — no Upload / History / RAG embeddings are persisted. Use
`/audio-notes` for anything durable.
paths:
/api/user/favorites:
post:
tags:
- History
summary: Retrieve user's favorite dialogues
description: >-
Returns history records marked as favorites by the authenticated user.
Uses the same HistoryRecord response shape as /histories. Results are
trimmed (inputs/outputs to 200 chars, tool responses to 80 chars).
Limited to 1000 records.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FavoritesQuery'
example:
institution: 60d5ec49f1b2c80015a4d1a1
responses:
'200':
description: Successfully retrieved favorite history dialogues
content:
application/json:
schema:
$ref: '#/components/schemas/FavoritesResponse'
examples:
successResponse:
summary: Successful response with favorites
value:
success: true
data:
- id: 688b024f7db6fe6e921399e3
created: '2025-07-01T12:00:00.000Z'
favorite: true
favorite_name: Deployment Guide
in:
input: How are you?
out:
outputs:
- I am doing wonderful, thank you for asking...
assistant:
_id: 60d5ec49f1b2c80015a4d1a4
name: My Assistant
liked_count: 5
'400':
description: Bad request or query error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Error getting favorites invalid ObjectId
error:
type: object
'401':
description: Unauthorized - user not found or invalid token
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Authentication Required!
security:
- apiKeyAuth: []
components:
schemas:
FavoritesQuery:
type: object
properties:
institution:
type: string
description: >-
Institution ObjectId. If omitted, uses the current user's
institution.
FavoritesResponse:
type: object
properties:
success:
type: boolean
description: Indicates if the request was successful
data:
type: array
items:
$ref: '#/components/schemas/HistoryRecord'
description: >-
Array of favorited history records (max 1000). Inputs/outputs
trimmed to 200 chars. Tool responses truncated to 80 chars.
message:
type: string
description: Error message when success is false
error:
type: object
description: Error object when success is false
HistoryRecord:
type: object
properties:
id:
type: string
description: Unique identifier for the history record
created:
type: string
format: date-time
description: Creation timestamp
credits:
type: integer
description: Credits consumed for this interaction
usage:
type: integer
description: Token usage count
cached:
type: integer
description: Cached tokens used
completion:
type: integer
description: Completion tokens generated
discount:
type: number
description: Credit discount applied to this interaction
latencyMs:
type: integer
description: Response latency in milliseconds
ragDurationMs:
type: integer
description: RAG vector search duration in milliseconds
hasRagSearch:
type: boolean
description: >
True when this turn ran retrieval and produced at least one segment.
The full structured array is NOT included in list responses — it can
be multi-KB per row (N chunks × multi-KB chunkText) and is fetched
lazily via `GET /api/user/history/{id}/ragSearch` on ``
expand.
ragSearchCount:
type: integer
description: >-
Number of retrieved segments for this turn (used by the UI summary
line).
ragSearchMode:
type: string
enum:
- RAG
- KAG
description: >-
Retrieval mode this turn was captured under (KAG when fusion is
enabled, otherwise RAG).
institution:
description: >-
Institution this record belongs to. Normally an ObjectId string
reference. When the request sets `allInstitutions: true` (cross-twin
search), this is populated as an object with _id, name, ainame, and
picture — or as `{personal: true}` for personal-account records.
oneOf:
- type: string
description: ObjectId of the institution this record belongs to
- type: object
description: >-
Populated institution details (returned when `allInstitutions:
true`)
properties:
_id:
type: string
description: Institution unique identifier
name:
type: string
description: Institution name
ainame:
type: string
description: Institution AI display name
picture:
type: string
description: Institution picture URL
personal:
type: boolean
description: >-
True when the record belongs to the user's personal account
(no institution).
user:
type: string
description: ObjectId of the user who owns this record
favorite:
type: boolean
description: Whether the record is marked as favorite
forgotten:
type: boolean
description: Whether the record is soft-deleted
course_id:
type: number
description: Associated course identifier
course_name:
type: string
description: Associated course name
role_id:
type: string
description: Role identifier used during this interaction
role_name:
type: string
description: Role name used during this interaction
query_duration_ms:
type: integer
description: Query processing duration in milliseconds
conversation_model:
type: string
description: AI model used for the conversation
success:
type: boolean
description: Whether the dialogue completed successfully
message:
type: string
description: Status or error message from the dialogue
thumbUpDown:
type: string
description: User feedback on the response (thumb up or down)
favorite_name:
type: string
description: Custom name assigned when the record is favorited
in:
type: object
description: User input data
properties:
input:
type: string
description: Primary user input text. Trimmed to 200 chars in list views.
inputs:
type: array
items:
type: string
description: >-
Alternate plural input array. Trimmed to 200 chars total in list
views.
out:
type: object
description: AI response data
properties:
output:
type: string
description: >-
Primary AI response text (singular). Trimmed to 200 chars in
list views.
outputs:
type: array
items:
type: string
description: >-
AI response outputs array. Trimmed to 200 chars total in list
views.
code:
type: string
description: Code block content from the AI response
code_language:
type: string
description: Programming language of the code block
error:
type: string
description: >-
Error message if the dialogue failed. Only present when an error
occurred.
assistant:
type: object
nullable: true
description: >-
Assistant associated with this record. Null if assistant was
deleted.
properties:
_id:
type: string
description: Assistant unique identifier
name:
type: string
description: Assistant name
liked_count:
type: integer
description: Number of likes for this assistant
picture_url:
type: string
description: >-
Assistant avatar image URL. Omitted when assistant name contains
'New Conversation'.
tools:
type: array
description: >-
Tools used during the interaction. Tool responses are truncated to
80 chars unless tools=true in the request.
items:
type: object
properties:
id:
type: string
description: Tool execution identifier
name:
type: string
description: Tool name used
arguments:
type: object
description: Arguments passed to the tool
response:
type: string
description: >-
Tool response text. Truncated to 80 chars with '...' suffix
when partialResponse is true.
responseLength:
type: integer
description: Full length of the original tool response
partialResponse:
type: boolean
description: >-
True when response was truncated (responseLength > 80 and
tools param not set)
success:
type: boolean
description: Whether tool execution was successful
_id:
type: string
description: Tool execution record identifier
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-access-token
description: JWT token passed in x-access-token header
````