API Reference

Complete REST API reference with 22 endpoints grouped by resource.

The Epitome REST API is served by a Hono application at /v1. All endpoints return JSON responses and require authentication. The base URL ishttps://epitome.fyi/v1 for the hosted service, or http://localhost:3000/v1 for self-hosted instances.

Authentication

The API supports two authentication methods:

Session Cookies (Dashboard)

Used by the React dashboard. After OAuth sign-in, a secure HTTP-only session cookie is set. All subsequent requests from the dashboard include this cookie automatically. Session-authenticated requests bypass the consent system since the user is interacting directly with their own data.

API Keys (Agents & Programmatic Access)

Used by AI agents and external integrations. Pass the API key in the Authorization header. API key requests are subject to the consent system — agents must be granted per-resource permissions by the user.

bash

curl -H "Authorization: Bearer epi_live_abc123..." \
  https://epitome.fyi/v1/profile

Profile

The profile is a versioned JSONB document containing the user's personal information. Every update creates a new version, preserving the full edit history.

GET/v1/profileSession / API Key

Retrieve the user's current profile with all fields, version number, and confidence score.

json

// Response
{
  "version": 12,
  "confidence": 0.87,
  "updated_at": "2026-02-15T10:30:00Z",
  "data": {
    "name": "Alice Chen",
    "timezone": "America/Los_Angeles",
    ...
  }
}

PATCH/v1/profileSession / API Key

Update the user's profile using deep merge. Only specified fields are changed; all other data is preserved. Creates a new version.

json

// Request body
{
  "timezone": "America/New_York",
  "preferences": { "food": { "favorites": ["sushi", "pizza"] } }
}

// Response: updated profile (same format as GET)

GET/v1/profile/historySession / API Key

Retrieve the version history of the user's profile, showing all past versions with timestamps and change summaries.

json

// Response
[
  { "version": 12, "updated_at": "2026-02-15T10:30:00Z", "changed_fields": ["timezone"] },
  { "version": 11, "updated_at": "2026-02-14T08:00:00Z", "changed_fields": ["preferences.food"] },
  ...
]

Tables

User tables are dynamic, schema-flexible collections for structured data. The schema is inferred from the first record inserted and can evolve over time.

GET/v1/tablesSession / API Key

List all user-defined tables with their record counts and schemas.

GET/v1/tables/:nameSession / API Key

Query records from a specific table. Supports filtering, sorting, pagination.

text

Query parameters:
  ?filter[status]=unread    Filter by field value
  ?sort=-created_at         Sort descending by field
  ?limit=20&offset=0        Pagination

POST/v1/tables/:nameSession / API Key

Insert a new record into a table. The table is created automatically if it does not exist.

json

// Request body
{
  "title": "Snow Crash",
  "author": "Neal Stephenson",
  "status": "unread"
}

PATCH/v1/tables/:name/:idSession / API Key

Update an existing record. Only specified fields are changed.

json

// Request body
{ "status": "reading" }

DELETE/v1/tables/:name/:idSession / API Key

Delete a record from a table. Returns the deleted record.

Vectors

Vector endpoints manage the semantic memory system. Content is automatically embedded using text-embedding-3-small and stored in pgvector for cosine similarity search.

POST/v1/vectors/:collection/searchSession / API Key

Perform semantic vector search within a collection (or across all collections if collection is 'all').

json

// Request body
{
  "query": "outdoor hobbies",
  "limit": 10,
  "min_similarity": 0.3
}

GET/v1/vectors/recentSession / API Key

Retrieve recently added vector entries across all collections, ordered by creation date.

POST/v1/vectors/:collectionSession / API Key

Store a new vector entry. The content is embedded automatically and entity extraction runs asynchronously.

json

// Request body
{
  "content": "I love hiking in the Cascades.",
  "metadata": { "source": "claude-desktop" }
}

GET/v1/vectors/collectionsSession / API Key

List all vector collections with entry counts and most recent activity.

Graph

The knowledge graph stores entities (people, places, organizations, concepts) and their typed relationships. Entities are extracted automatically from stored memories.

GET/v1/graph/entitiesSession / API Key

List entities in the knowledge graph. Supports filtering by type and name search.

text

Query parameters:
  ?type=person              Filter by entity type
  ?name=Emma                Search by name (substring match)
  ?limit=50&offset=0        Pagination

GET/v1/graph/entities/:id/neighborsSession / API Key

Get all entities connected to a specific entity, along with the edges between them.

PATCH/v1/graph/entities/:idSession / API Key

Update an entity's properties or name. Useful for correcting auto-extracted data.

json

// Request body
{
  "name": "Emma Chen",
  "properties": { "age": 7, "school": "Lincoln Elementary" }
}

DELETE/v1/graph/entities/:idSession / API Key

Delete an entity and all its edges. Use with caution — this cannot be undone.

POST/v1/graph/entities/mergeSession / API Key

Merge two duplicate entities into one. Combines edges, mentions, and properties. The target entity is kept; the source entity is deleted.

json

// Request body
{
  "source_id": "ent_003",
  "target_id": "ent_001"
}

GET/v1/graph/statsSession / API Key

Get summary statistics about the knowledge graph: entity counts by type, edge counts by type, total mentions.

Memory

The memory quality engine identifies contradictions, stale data, and low-confidence facts for human review. These endpoints power the Review page in the dashboard.

GET/v1/memory/reviewSession only

List memory entries flagged for review. Includes contradictions, stale data, and low-confidence items with suggested resolutions.

json

// Response
{
  "items": [
    {
      "id": "rev_001",
      "type": "contradiction",
      "entries": ["vec_010", "vec_015"],
      "description": "Conflicting timezone: 'Pacific Time' vs 'Eastern Time'",
      "suggested_action": "keep_newer",
      "created_at": "2026-02-16T12:00:00Z"
    }
  ]
}

POST/v1/memory/review/:id/resolveSession only

Resolve a flagged memory review item. The user chooses which data to keep, merge, or discard.

json

// Request body
{
  "action": "keep_newer",
  "note": "I moved to the East Coast in January"
}

Activity

The activity log provides an audit trail of all agent and user actions. Every MCP tool call, API request, and dashboard action is logged.

GET/v1/activitySession / API Key

Retrieve the activity log with filtering by agent, action type, and date range.

text

Query parameters:
  ?agent_id=agent_001       Filter by agent
  ?action=store_memory      Filter by action type
  ?from=2026-02-01          Start date (ISO 8601)
  ?to=2026-02-17            End date (ISO 8601)
  ?limit=50&offset=0        Pagination

Agents

Manage the AI agents that have access to your Epitome data. Each agent has its own API key and consent permissions.

GET/v1/agentsSession only

List all registered agents with their names, last active times, and consent grants.

PATCH/v1/agents/:idSession only

Update an agent's name or consent permissions.

json

// Request body
{
  "name": "My Claude Desktop",
  "consent": {
    "profile": "read",
    "tables": "read_write",
    "vectors": "read_write",
    "graph": "read"
  }
}

DELETE/v1/agents/:idSession only

Revoke an agent's access and delete its API key. The agent will no longer be able to connect.

Error Handling

All API errors follow a consistent JSON format. The HTTP status code indicates the error category, and the response body provides details.

json

// Standard error response format
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      { "field": "content", "message": "Required field is missing" }
    ]
  }
}

Status	Code	Description
400	VALIDATION_ERROR	Request body or query parameters failed validation
401	UNAUTHORIZED	Missing or invalid authentication credentials
403	CONSENT_REQUIRED	Agent lacks consent for the requested resource
404	NOT_FOUND	Resource does not exist
429	RATE_LIMITED	Too many requests — wait and retry
500	INTERNAL_ERROR	Unexpected server error

MCP Tools Reference Self-Hosting Guide