The Prompts API tracks user prompts (questions/requests sent to AI) for context and searchability.
Add Prompt
POST /prompts
Store a user prompt.
Request Body
Session ID this prompt belongs to
The full prompt text (max 2000 chars, automatically truncated)
Project name for filtering
Response
The prompt ID (auto-incremented)
Example
curl -X POST http://127.0.0.1:7437/prompts \
-H "Content-Type: application/json" \
-d '{
"session_id": "session-abc123",
"project": "engram",
"content": "How do I implement token refresh in the authentication flow?"
}'
{
"id": 15,
"status": "saved"
}
Get Recent Prompts
GET /prompts/recent
Retrieve recent prompts, optionally filtered by project.
Query Parameters
Maximum prompts to return (1-100)
Response
Returns an array of prompts:
Project name (empty string if not set)
Example
curl "http://127.0.0.1:7437/prompts/recent?project=engram&limit=5"
[
{
"id": 15,
"session_id": "session-abc123",
"content": "How do I implement token refresh in the authentication flow?",
"project": "engram",
"created_at": "2024-03-15 14:25:00"
},
{
"id": 14,
"session_id": "session-abc123",
"content": "Show me the current session management code",
"project": "engram",
"created_at": "2024-03-15 14:10:00"
}
]
Search Prompts
GET /prompts/search
Search prompts using full-text search (FTS5).
Query Parameters
Search query. Supports multiple words, automatically quoted for safety.
Maximum results to return (1-100)
Response
Returns an array of matching prompts (same schema as Get Recent Prompts).
Example
curl "http://127.0.0.1:7437/prompts/search?q=authentication&project=engram"
[
{
"id": 15,
"session_id": "session-abc123",
"content": "How do I implement token refresh in the authentication flow?",
"project": "engram",
"created_at": "2024-03-15 14:25:00"
},
{
"id": 12,
"session_id": "session-def456",
"content": "Debug authentication middleware issues",
"project": "engram",
"created_at": "2024-03-14 11:30:00"
}
]
Search Behavior
Query Sanitization
Prompt search uses the same FTS5 sanitization as observations search:
Input: "token refresh"
FTS5: "token" "refresh"
Searched Fields
content - Full prompt textproject - Project name
Multi-Word Queries
Multi-word queries match prompts containing all terms (AND logic):
curl "http://127.0.0.1:7437/prompts/search?q=token%20refresh%20flow"
# Matches: prompts with "token" AND "refresh" AND "flow"
Privacy
Prompts support <private>...</private> tags to prevent sensitive data storage:
{
"content": "Use API key <private>sk-1234567890</private> for authentication"
}
{
"content": "Use API key [REDACTED] for authentication"
}
Error Handling
Missing Required Fields
curl -X POST http://127.0.0.1:7437/prompts \
-H "Content-Type: application/json" \
-d '{"session_id": "session-123"}'
{
"error": "session_id and content are required"
}
Missing Search Query
curl "http://127.0.0.1:7437/prompts/search?project=engram"
{
"error": "q parameter is required"
}
Prompt Schema
Complete prompt object structure:
interface Prompt {
id: number;
session_id: string;
content: string;
project: string; // Empty string if not set
created_at: string; // ISO 8601
}
Use Cases
- Context Building - Show recent prompts to provide conversation context
- Pattern Detection - Identify frequently asked questions
- Debugging - Trace what users asked before encountering issues
- Analytics - Understand common user workflows and pain points
Retention
Prompts are stored indefinitely. Use the export/import API to backup or migrate prompt data.