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).Unique history entry ID
User’s unique identifier
The original search query text
Chapter number of the matched verse (1-18)
Verse number of the matched verse
English translation of the matched verse
Contextual commentary generated for the query
Complete traditional commentary (may be null)
ISO 8601 timestamp when the query was made
Response Example
Error Responses
| Status Code | Description |
|---|---|
| 401 | Unauthorized - authentication required |
| 429 | Rate limit exceeded (30 requests per minute) |
| 500 | Failed to fetch history |
| 503 | Database 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
Error Responses
| Status Code | Description |
|---|---|
| 401 | Unauthorized |
| 429 | Rate limit exceeded (5 requests per minute) |
| 500 | Failed to clear history |
| 503 | Database 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
How History is Populated
History entries are automatically created when users make queries via the/api/query endpoint:
- User submits a query to
/api/query - Backend returns a matched verse with commentary
- Frontend saves the query and result to history (fire-and-forget)
- 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