> ## 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.

# API Overview

> Complete reference for the Engram HTTP API

Engram provides a simple JSON REST API for storing and retrieving observations from AI coding sessions. All endpoints return JSON responses.

## Base URL

The API runs locally on your machine:

```
http://127.0.0.1:7437
```

The default port is `7437`. You can configure this via:

* `ENGRAM_PORT` environment variable
* Command line argument: `engram serve 8080`

## Authentication

Engram runs locally and does not require authentication. All API endpoints are accessible without credentials.

## Request Format

All POST/PATCH requests expect JSON bodies with `Content-Type: application/json`.

```bash theme={null}
curl -X POST http://127.0.0.1:7437/sessions \
  -H "Content-Type: application/json" \
  -d '{"id": "session-123", "project": "my-app"}'
```

## Response Format

All responses are JSON. Successful responses return appropriate HTTP status codes (200, 201, etc.) with data. Errors return 4xx/5xx codes with an error message:

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

## Common Status Codes

* `200 OK` - Request succeeded
* `201 Created` - Resource created successfully
* `400 Bad Request` - Invalid request parameters
* `404 Not Found` - Resource not found
* `500 Internal Server Error` - Server error

## Health Check

Check if the server is running:

```bash theme={null}
curl http://127.0.0.1:7437/health
```

### Response

```json theme={null}
{
  "status": "ok",
  "service": "engram",
  "version": "0.1.0"
}
```

## API Endpoints

The API is organized into the following sections:

* [Sessions](/api/sessions) - Manage coding sessions
* [Observations](/api/observations) - Store and retrieve memories
* [Search](/api/search) - Full-text search with FTS5
* [Prompts](/api/prompts) - Track user prompts

## Data Types

### Timestamps

All timestamps are in ISO 8601 format (UTC):

```
2024-03-15 14:30:00
```

### Nullable Fields

Optional fields are omitted or set to `null` in responses.

## Rate Limits

There are no rate limits for the local API.

## Privacy

Engram supports `<private>...</private>` tags to prevent sensitive data from being stored. Content within these tags is automatically stripped and replaced with `[REDACTED]` before persistence.

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

Stored as:

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