Skip to main content

History Endpoints

Manage query history for authenticated users. Track all previous queries and their results.

GET /api/history

Retrieve the complete query history for the authenticated user.

Authentication

Requires Clerk authentication. Include authentication headers with the request.

Response

Returns an array of previous queries sorted by creation date (newest first).
[].id
integer
Unique history entry ID
[].user_id
string
User’s unique identifier
[].query
string
The original search query text
[].chapter
integer
Chapter number of the matched verse (1-18)
[].verse
integer
Verse number of the matched verse
[].translation
string
English translation of the matched verse
[].summarized_commentary
string
Contextual commentary generated for the query
[].full_commentary
string
Complete traditional commentary (may be null)
[].created_at
string
ISO 8601 timestamp when the query was made

Response Example

[
  {
    "id": 456,
    "user_id": "user_abc123",
    "query": "How do I overcome fear and anxiety?",
    "chapter": 2,
    "verse": 47,
    "translation": "You have the right to perform your prescribed duties...",
    "summarized_commentary": "When facing fear and anxiety, focus on your actions...",
    "full_commentary": "...",
    "created_at": "2024-03-10T12:34:56.789Z"
  },
  {
    "id": 455,
    "user_id": "user_abc123",
    "query": "What is the meaning of life?",
    "chapter": 3,
    "verse": 19,
    "translation": "Therefore, without attachment, perform always the work...",
    "summarized_commentary": "The meaning of life is found in performing one's duty...",
    "full_commentary": null,
    "created_at": "2024-03-09T10:20:30.123Z"
  }
]

Error Responses

Status CodeDescription
401Unauthorized - authentication required
429Rate limit exceeded (30 requests per minute)
500Failed to fetch history
503Database not configured

DELETE /api/history

Clear all query history for the authenticated user.

Authentication

Requires Clerk authentication.

Request

No parameters required. Deletes all history entries for the authenticated user.

Response

{
  "success": true
}

Error Responses

Status CodeDescription
401Unauthorized
429Rate limit exceeded (5 requests per minute)
500Failed to clear history
503Database not configured

Rate Limiting

  • GET: 30 requests per minute per client
  • DELETE: 5 requests per minute per client (stricter limit for destructive operation)

Code Examples

curl -X GET https://gitachat.org/api/history \
  -H "Authorization: Bearer YOUR_TOKEN"

How History is Populated

History entries are automatically created when users make queries via the /api/query endpoint:
  1. User submits a query to /api/query
  2. Backend returns a matched verse with commentary
  3. Frontend saves the query and result to history (fire-and-forget)
  4. History write failures don’t block the query response

Privacy Notes

  • History is private to each user
  • Other users cannot access your query history
  • Clearing history is permanent and cannot be undone
  • History is stored in Supabase with user authentication

Build docs developers (and LLMs) love