> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField body="session_id" type="string" required>
  Session ID this prompt belongs to
</ParamField>

<ParamField body="content" type="string" required>
  The full prompt text (max 2000 chars, automatically truncated)
</ParamField>

<ParamField body="project" type="string">
  Project name for filtering
</ParamField>

### Response

<ResponseField name="id" type="integer">
  The prompt ID (auto-incremented)
</ResponseField>

<ResponseField name="status" type="string">
  Always "saved"
</ResponseField>

### Example

```bash theme={null}
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?"
  }'
```

```json theme={null}
{
  "id": 15,
  "status": "saved"
}
```

## Get Recent Prompts

`GET /prompts/recent`

Retrieve recent prompts, optionally filtered by project.

### Query Parameters

<ParamField query="project" type="string">
  Filter by project name
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Maximum prompts to return (1-100)
</ParamField>

### Response

Returns an array of prompts:

<ResponseField name="id" type="integer">
  Prompt ID
</ResponseField>

<ResponseField name="session_id" type="string">
  Session ID
</ResponseField>

<ResponseField name="content" type="string">
  Full prompt text
</ResponseField>

<ResponseField name="project" type="string">
  Project name (empty string if not set)
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp
</ResponseField>

### Example

```bash theme={null}
curl "http://127.0.0.1:7437/prompts/recent?project=engram&limit=5"
```

```json theme={null}
[
  {
    "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

<ParamField query="q" type="string" required>
  Search query. Supports multiple words, automatically quoted for safety.
</ParamField>

<ParamField query="project" type="string">
  Filter by project name
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Maximum results to return (1-100)
</ParamField>

### Response

Returns an array of matching prompts (same schema as Get Recent Prompts).

### Example

```bash theme={null}
curl "http://127.0.0.1:7437/prompts/search?q=authentication&project=engram"
```

```json theme={null}
[
  {
    "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):

```bash theme={null}
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:

```json theme={null}
{
  "content": "Use API key <private>sk-1234567890</private> for authentication"
}
```

Stored as:

```json theme={null}
{
  "content": "Use API key [REDACTED] for authentication"
}
```

## Error Handling

### Missing Required Fields

```bash theme={null}
curl -X POST http://127.0.0.1:7437/prompts \
  -H "Content-Type: application/json" \
  -d '{"session_id": "session-123"}'
```

```json theme={null}
{
  "error": "session_id and content are required"
}
```

### Missing Search Query

```bash theme={null}
curl "http://127.0.0.1:7437/prompts/search?project=engram"
```

```json theme={null}
{
  "error": "q parameter is required"
}
```

## Prompt Schema

Complete prompt object structure:

```typescript theme={null}
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.