# API Documentation

## System Prompts

### Overview

System prompts are managed instructions automatically injected into LLM requests. They support scoping at project, subject, or chat level.

- **project**: Applies to all requests in the project (default).
- **subject**: Applies only to requests with a matching `subject_id`.
- **chat**: Applies only to requests with a matching `chat_id`.

Prompts are layered: project → subject → chat. Multiple prompts are concatenated.

Dynamic Context is supported with `{{var_name}}` tokens via the `template` object. Integration resolution is controlled by `MNX_PROMPT_TEMPLATE_RENDER_ENABLED`.

### Endpoint: GET `/api/v1/prompts`

- **Description**: List all system prompts for your project.
- **Scope**: `prompts:read`

**Request**:

```bash
curl "https://www.mnexium.com/api/v1/prompts" \
  -H "x-mnexium-key: $MNX_KEY"
```

**Response**:

```json
{
  "prompts": [
    {
      "id": "sp_abc123",
      "name": "Default Assistant",
      "prompt_text": "You are a helpful assistant.",
      "scope": "project",
      "is_default": true,
      "priority": 100
    }
  ]
}
```

### Endpoint: POST `/api/v1/prompts`

- **Description**: Create a new system prompt. Set `is_default: true` for auto-injection.
- **Scope**: `prompts:write`

**Request**:

```bash
curl -X POST "https://www.mnexium.com/api/v1/prompts" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default Assistant",
    "prompt_text": "You are a helpful assistant for {{customer_name}}.",
    "scope": "project",
    "is_default": true,
    "template": {
      "enabled": true,
      "variables": {
        "customer_name": {
          "source": "integration",
          "integration_id": "int_crm",
          "key": "customer_name",
          "live_fetch": false,
          "default": "customer"
        }
      }
    }
  }'
```

**Response**:

```json
{
  "ok": true,
  "prompt": {
    "id": "sp_abc123",
    "name": "Default Assistant",
    "scope": "project"
  }
}
```

### Endpoint: PATCH `/api/v1/prompts/:id`

- **Description**: Update an existing system prompt. Only provided fields are updated.
- **Scope**: `prompts:write`

**Request**:

```bash
curl -X PATCH "https://www.mnexium.com/api/v1/prompts/sp_abc123" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "You are a friendly assistant.",
    "is_default": true
  }'
```

**Response**:

```json
{
  "ok": true,
  "id": "sp_abc123",
  "updated": true
}
```

### Endpoint: DELETE `/api/v1/prompts/:id`

- **Description**: Soft-delete a system prompt. The prompt is deactivated but retained for audit purposes.
- **Scope**: `prompts:delete`

**Request**:

```bash
curl -X DELETE "https://www.mnexium.com/api/v1/prompts/sp_abc123" \
  -H "x-mnexium-key: $MNX_KEY"
```

**Response**:

```json
{
  "ok": true,
  "id": "sp_abc123",
  "deleted": true
}
```

### Endpoint: GET `/api/v1/prompts/resolve`

- **Description**: Preview which prompts will be injected for a given context.
- **Scope**: `prompts:read`

**Request**:

```bash
curl -G "https://www.mnexium.com/api/v1/prompts/resolve" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "subject_id=user_123" \
  --data-urlencode "combined=true"
```

**Response** when `combined=true`:

```json
{
  "prompt_text": "You are a helpful assistant.\n\nThis user prefers concise responses.",
  "has_prompt": true
}
```

**Response** when `combined=false` (default):

```json
{
  "prompts": [
    { "id": "sp_abc123", "scope": "project" },
    { "id": "sp_def456", "scope": "subject" }
  ],
  "count": 2
}
```

### Using `system_prompt` and `memory_policy` in Requests

Control system prompt injection and memory extraction policy via `mnx.system_prompt` and `mnx.memory_policy`:

```json
{
  "mnx": { "subject_id": "user_123" }
}
```

### Example requests:

- Skip system prompt injection:

```json
{
  "mnx": { "system_prompt": false }
}
```

- Use a specific prompt by ID:

```json
{
  "mnx": { "system_prompt": "sp_sales_assistant" }
}
```

- Use a specific memory policy by ID:

```json
{
  "mnx": { "memory_policy": "mp_support_assistant" }
}
```

- Disable memory policy for this request:

```json
{
  "mnx": { "memory_policy": false }
}
```