Prompts API

Store and search user prompts

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 · string · required

Session ID this prompt belongs to

content · string · required

The full prompt text (max 2000 chars, automatically truncated)

project · string

Project name for filtering

Response

id · integer

The prompt ID (auto-incremented)

status · string

Always “saved”

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

project · string

Filter by project name

limit · integer · default: "20"

Maximum prompts to return (1-100)

Response

Returns an array of prompts:

id · integer

Prompt ID

session_id · string

Session ID

content · string

Full prompt text

project · string

Project name (empty string if not set)

created_at · string

ISO 8601 timestamp

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

q · string · required

Search query. Supports multiple words, automatically quoted for safety.

project · string

Filter by project name

limit · integer · default: "10"

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 text
• project - 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"
}

Stored as:

{
  "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

1. Context Building - Show recent prompts to provide conversation context
2. Pattern Detection - Identify frequently asked questions
3. Debugging - Trace what users asked before encountering issues
4. Analytics - Understand common user workflows and pain points

Retention

Prompts are stored indefinitely. Use the export/import API to backup or migrate prompt data.