Skip to content

API Reference

Jump to bottom
hitchhiker edited this page Feb 5, 2026 · 4 revisions

REST API Reference

Fold provides a comprehensive REST API for memory management, search, knowledge graph operations, and authentication. All endpoints use JSON for request and response bodies. Most endpoints require Bearer token authentication.

Base URL

https://fold.example.com/api

Replace fold.example.com with your Fold instance URL.

Authentication

Bearer Tokens

Most endpoints require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer fold_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://fold.example.com/api/projects

API tokens are created by authenticated users and inherit all project access from the user who created them. Access is controlled through project membership, not token-level scoping.

Session Cookies

Web UI endpoints use session cookies (httpOnly, secure):

curl -b "session=..." https://fold.example.com/api/auth/me

Error Responses

All errors follow this format:

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "API token is invalid or expired",
    "status": 401,
    "details": {
      "field": "authorization"
    }
  }
}

Common Error Codes

Code Status Meaning
INVALID_TOKEN 401 Bearer token missing, invalid, or expired
FORBIDDEN 403 Token doesn't have access to this project
NOT_FOUND 404 Resource doesn't exist
CONFLICT 409 Resource already exists
RATE_LIMITED 429 Too many requests, retry after delay
INTERNAL_ERROR 500 Server error (check logs)
SERVICE_UNAVAILABLE 503 Qdrant or external service down

Projects

Create Project

Endpoint: POST /projects

Auth: Bearer token

Description: Create a new project. Every project is a repository with a provider type and root path.

Request:

{
  "slug": "my-app",
  "name": "My Application",
  "description": "Optional description",
  "provider": "local",
  "root_path": "/path/to/project",
  "remote_owner": null,
  "remote_repo": null,
  "remote_branch": null,
  "access_token": null
}

Provider Types:

  • local - Local filesystem directory (requires root_path)
  • github - GitHub repository (requires remote_owner, remote_repo, access_token)
  • gitlab - GitLab repository (requires remote_owner, remote_repo, access_token)

Parameters:

  • slug (required) - URL-friendly identifier
  • name (required) - Display name
  • description (optional) - Project description
  • provider (required) - One of: local, github, gitlab
  • root_path (required) - Path where fold/ directory lives
  • remote_owner (optional) - GitHub/GitLab username or organisation
  • remote_repo (optional) - Repository name
  • remote_branch (optional) - Branch to index (default: main)
  • access_token (optional) - GitHub/GitLab personal access token

Response: 201 Created

{
  "id": "proj_abc123",
  "slug": "my-app",
  "name": "My Application",
  "description": "Optional description",
  "provider": "local",
  "root_path": "/path/to/project",
  "created_at": "2026-02-03T10:00:00Z"
}

List Projects

Endpoint: GET /projects

Auth: Bearer token

Description: List all projects your token can access.

Query Parameters:

  • limit (default: 50) - Max projects to return
  • offset (default: 0) - Pagination offset

Response: 200 OK

{
  "projects": [
    {
      "id": "proj_abc123",
      "slug": "my-app",
      "name": "My Application",
      "description": "...",
      "created_at": "2026-02-03T10:00:00Z",
      "memory_count": 5432,
      "last_activity": "2026-02-03T14:22:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Project

Endpoint: GET /projects/:slug

Auth: Bearer token

Description: Get details about a specific project.

Path Parameters:

  • slug - Project slug (e.g., "my-app")

Response: 200 OK

{
  "id": "proj_abc123",
  "slug": "my-app",
  "name": "My Application",
  "description": "...",
  "provider": "github",
  "root_path": "/path/to/project",
  "remote_owner": "myorg",
  "remote_repo": "myrepo",
  "remote_branch": "main",
  "created_at": "2026-02-03T10:00:00Z",
  "stats": {
    "total_memories": 5432,
    "last_activity": "2026-02-03T14:22:00Z"
  }
}

Trigger Sync

Endpoint: POST /projects/:slug/sync

Auth: Bearer token

Description: Manually trigger project indexing.

Response: 200 OK

{
  "job_id": "job_abc123",
  "status": "queued",
  "message": "Project sync queued for processing"
}

Memories

All memories use a unified model with a source field (File, Agent, Git).

Create Memory

Endpoint: POST /projects/:slug/memories

Auth: Bearer token

Description: Create a new memory manually or via agent.

Request:

{
  "title": "Session Management Notes",
  "type": "session",
  "source": "Agent",
  "content": "Today we refactored session handling...",
  "keywords": ["sessions", "auth"],
  "tags": ["refactoring", "backend"],
  "auto_metadata": true
}

Parameters:

  • title (required) - Human-readable title
  • type (required) - Memory type: codebase, session, spec, decision, commit, pr, task, general
  • source (required) - File, Agent, or Git
  • content (required) - Memory content (markdown)
  • keywords (optional) - Key terms (array, max 15)
  • tags (optional) - Category tags (array, max 6)
  • auto_metadata (optional) - Auto-analyse content (default: false)

Response: 201 Created

{
  "id": "aBcD123456789abc",
  "project_id": "proj_abc123",
  "title": "Session Management Notes",
  "type": "session",
  "source": "Agent",
  "author": "user_123",
  "keywords": ["sessions", "auth"],
  "tags": ["refactoring", "backend"],
  "context": "Session management refactoring...",
  "created_at": "2026-02-03T10:30:00Z",
  "updated_at": "2026-02-03T10:30:00Z"
}

List Memories

Endpoint: GET /projects/:slug/memories

Auth: Bearer token

Description: List memories in a project.

Query Parameters:

  • limit (default: 50) - Max memories to return
  • offset (default: 0) - Pagination offset
  • source (optional) - Filter by source (File, Agent, Git)
  • type (optional) - Filter by type (codebase, session, spec, etc.)
  • sort (optional) - Sort by: created_at, updated_at, relevance

Response: 200 OK

{
  "memories": [
    {
      "id": "aBcD123456789abc",
      "title": "Authentication Service",
      "type": "codebase",
      "source": "File",
      "file_path": "src/auth/service.ts",
      "language": "typescript",
      "created_at": "2026-02-03T10:30:00Z"
    }
  ],
  "total": 5432,
  "limit": 50,
  "offset": 0
}

Get Memory

Endpoint: GET /projects/:slug/memories/:id

Auth: Bearer token

Description: Get a specific memory with full content.

Path Parameters:

  • slug - Project slug
  • id - Memory ID (16-char hash)

Response: 200 OK

{
  "id": "aBcD123456789abc",
  "project_id": "proj_abc123",
  "title": "Authentication Service",
  "type": "codebase",
  "source": "File",
  "file_path": "src/auth/service.ts",
  "language": "typescript",
  "author": "system",
  "keywords": ["auth", "jwt", "security"],
  "tags": ["auth", "typescript"],
  "context": "Implements JWT-based authentication...",
  "content": "Full markdown content...",
  "created_at": "2026-02-03T10:30:00Z",
  "updated_at": "2026-02-03T10:30:00Z",
  "retrieval_count": 47,
  "last_accessed": "2026-02-03T14:15:00Z"
}

Update Memory

Endpoint: PUT /projects/:slug/memories/:id

Auth: Bearer token

Description: Update memory metadata or content.

Request:

{
  "title": "New title",
  "content": "Updated content",
  "keywords": ["new", "keywords"],
  "tags": ["new", "tags"],
  "context": "Updated context"
}

Response: 200 OK

{
  "id": "aBcD123456789abc",
  "title": "New title",
  "content": "Updated content",
  "keywords": ["new", "keywords"],
  "tags": ["new", "tags"],
  "context": "Updated context",
  "updated_at": "2026-02-03T15:00:00Z"
}

Delete Memory

Endpoint: DELETE /projects/:slug/memories/:id

Auth: Bearer token

Description: Delete a memory and its relationships.

Response: 204 No Content

Search and Context

Semantic Search

Endpoint: POST /projects/:slug/search

Auth: Bearer token

Description: Search memories by meaning using embeddings and optional decay weighting.

Request:

{
  "query": "How do we handle user authentication?",
  "limit": 10,
  "offset": 0,
  "type": null,
  "source": null,
  "include_decay": true,
  "decay_weight": 0.3
}

Parameters:

  • query (required) - Natural language search query
  • limit (default: 10) - Max results
  • offset (default: 0) - Pagination
  • type (optional) - Filter by memory type
  • source (optional) - Filter by source
  • include_decay (default: true) - Apply memory decay weighting
  • decay_weight (default: 0.3) - Strength weighting (0=pure semantic, 1=pure strength)

Response: 200 OK

{
  "results": [
    {
      "id": "aBcD123456789abc",
      "title": "Authentication Service",
      "type": "codebase",
      "source": "File",
      "relevance": 0.95,
      "decay_strength": 0.87,
      "combined_score": 0.92,
      "snippet": "Handles JWT validation and session management..."
    },
    {
      "id": "f0123456789abcde",
      "title": "Use JWT for authentication",
      "type": "decision",
      "source": "Agent",
      "relevance": 0.91,
      "decay_strength": 0.92,
      "combined_score": 0.91,
      "snippet": "We chose JWT because it is stateless and scalable..."
    }
  ],
  "total": 34,
  "limit": 10,
  "offset": 0
}

Get Context (Holographic)

Endpoint: POST /projects/:slug/context/:id

Auth: Bearer token

Description: Get holographic context around a memory - includes related memories and nested relationships.

Request:

{
  "depth": 2
}

Parameters:

  • depth (default: 2) - How deep to traverse relationships (1-3)

Response: 200 OK

{
  "memory": {
    "id": "aBcD123456789abc",
    "title": "Authentication Service",
    "type": "codebase",
    "source": "File",
    "content": "..."
  },
  "related_memories": [
    {
      "id": "f0123456789abcde",
      "title": "Use JWT for authentication",
      "type": "decision",
      "link_type": "Related",
      "relevance": 0.92
    },
    {
      "id": "9a8b7c6d5e4f3g2h",
      "title": "Session Timeout Policy",
      "type": "decision",
      "link_type": "Related",
      "relevance": 0.87
    }
  ],
  "similar_memories": [
    {
      "id": "c1234d5678e9f0g1",
      "title": "OAuth Integration",
      "type": "codebase",
      "relevance": 0.81
    }
  ],
  "depth_traversed": 2
}

Memory Links

Create Link

Endpoint: POST /projects/:slug/memories/:id/links

Auth: Bearer token

Description: Create a relationship between two memories.

Request:

{
  "target_id": "f0123456789abcde",
  "link_type": "Related",
  "metadata": {
    "confidence": 0.92,
    "reasoning": "Both about authentication"
  }
}

Parameters:

  • target_id (required) - Target memory ID
  • link_type (required) - Related, References, DependsOn, or Modifies
  • metadata (optional) - Additional metadata

Response: 201 Created

{
  "id": "link_123",
  "source_id": "aBcD123456789abc",
  "target_id": "f0123456789abcde",
  "link_type": "Related",
  "metadata": {
    "confidence": 0.92,
    "reasoning": "Both about authentication"
  },
  "created_at": "2026-02-03T10:30:00Z"
}

List Links

Endpoint: GET /projects/:slug/memories/:id/links

Auth: Bearer token

Description: List all links connected to a memory.

Query Parameters:

  • direction (optional) - incoming, outgoing, or both (default: both)

Response: 200 OK

{
  "links": [
    {
      "id": "link_123",
      "source_id": "aBcD123456789abc",
      "target_id": "f0123456789abcde",
      "link_type": "Related",
      "direction": "outgoing"
    }
  ],
  "total": 3
}

Delete Link

Endpoint: DELETE /projects/:slug/memories/:id/links/:link_id

Auth: Bearer token

Description: Remove a link between memories.

Response: 204 No Content

Authentication

List Auth Providers

Endpoint: GET /auth/providers

Auth: None (public)

Description: Get available login providers.

Response: 200 OK

{
  "providers": [
    {
      "id": "google",
      "display_name": "Google",
      "icon": "google"
    },
    {
      "id": "github",
      "display_name": "GitHub",
      "icon": "github"
    }
  ]
}

Initiate Login

Endpoint: GET /auth/login/:provider

Auth: None (public)

Description: Redirect user to OIDC/OAuth provider login.

Path Parameters:

  • provider - Provider ID from /auth/providers

Response: 302 Redirect

Redirects to provider's authorization endpoint.

Login Callback

Endpoint: GET /auth/callback/:provider

Auth: None (public)

Description: OAuth/OIDC callback endpoint (called by auth provider).

Query Parameters:

  • code - Authorization code from provider
  • state - CSRF protection state

Response: 302 Redirect

Redirects to UI with session cookie set.

Get Current User

Endpoint: GET /auth/me

Auth: Bearer token or session

Description: Get current authenticated user's details.

Response: 200 OK

{
  "id": "user_abc123",
  "provider": "google",
  "email": "jane@example.com",
  "display_name": "Jane Doe",
  "avatar_url": "https://...",
  "accessible_projects": [
    { "id": "proj_1", "slug": "myapp", "name": "My App" }
  ]
}

Logout

Endpoint: POST /auth/logout

Auth: Session cookie

Description: Clear session and invalidate token.

Request: (empty body)

Response: 204 No Content

API Token Management

List My Tokens

Endpoint: GET /me/tokens

Auth: Bearer token or session

Description: List all API tokens created by current user.

Query Parameters:

  • limit (default: 50) - Max tokens to return
  • offset (default: 0) - Pagination

Response: 200 OK

{
  "tokens": [
    {
      "id": "token_abc123",
      "name": "Claude Code Token",
      "created_at": "2026-01-15T10:00:00Z",
      "last_used": "2026-02-03T14:22:00Z"
    }
  ],
  "total": 2
}

Create Token

Endpoint: POST /me/tokens

Auth: Bearer token or session

Description: Create a new API token.

Request:

{
  "name": "Claude Code Token"
}

Response: 201 Created

{
  "id": "token_abc123",
  "name": "Claude Code Token",
  "token": "fold_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-02-03T10:00:00Z"
}

Note: Token value is only shown once at creation. Store it securely.

The token inherits access from the user who created it. Access is controlled via project membership, not token-level scoping.

Revoke Token

Endpoint: DELETE /me/tokens/:id

Auth: Bearer token or session

Description: Revoke an API token.

Response: 204 No Content

Webhooks

GitHub Webhook

Endpoint: POST /webhooks/github/:project_id

Auth: None (webhook token verification)

Description: GitHub push webhook endpoint. Called automatically when code is pushed to a project with provider: github.

Request: GitHub push event payload

Response: 200 OK

{
  "status": "received",
  "job_id": "job_abc123"
}

GitLab Webhook

Endpoint: POST /webhooks/gitlab/:project_id

Auth: None (webhook token verification)

Description: GitLab push webhook endpoint. Called automatically when code is pushed to a project with provider: gitlab.

Request: GitLab push event payload

Response: 200 OK

{
  "status": "received",
  "job_id": "job_abc123"
}

Status and Health

Health Check

Endpoint: GET /health

Auth: None (public)

Description: Check if Fold server is running and healthy.

Response: 200 OK

{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2026-02-03T15:00:00Z",
  "dependencies": {
    "database": "ok",
    "qdrant": "ok",
    "llm": "ok"
  }
}

Job Queue Status

Endpoint: GET /status/jobs

Auth: Bearer token

Description: Get overview of background job queue.

Query Parameters:

  • status (optional) - Filter by status (pending, processing, completed, failed)
  • limit (default: 50) - Max jobs to return

Response: 200 OK

{
  "jobs": [
    {
      "id": "job_abc123",
      "project_id": "proj_abc123",
      "job_type": "index_repo",
      "status": "processing",
      "progress": { "files_processed": 42, "files_total": 100 },
      "created_at": "2026-02-03T10:00:00Z",
      "started_at": "2026-02-03T10:05:00Z"
    }
  ],
  "total": 1,
  "pending_count": 3,
  "processing_count": 1,
  "completed_count": 156
}

Job Details

Endpoint: GET /status/jobs/:id

Auth: Bearer token

Description: Get detailed information about a specific job.

Response: 200 OK

{
  "id": "job_abc123",
  "project_id": "proj_abc123",
  "job_type": "index_repo",
  "status": "processing",
  "progress": {
    "files_processed": 42,
    "files_total": 100,
    "current_file": "src/auth.ts",
    "percent": 42
  },
  "payload": {
    "project_id": "proj_123",
    "branch": "main"
  },
  "attempts": 1,
  "error": null,
  "created_at": "2026-02-03T10:00:00Z",
  "started_at": "2026-02-03T10:05:00Z"
}

Model Context Protocol (MCP)

Fold exposes all tools via MCP for AI agents.

MCP Endpoint

Endpoint: POST /mcp

Auth: Bearer token in header

Description: JSON-RPC endpoint for MCP tool calls.

Request Format:

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "project": "my-project",
      "query": "..."
    }
  }
}

Response Format:

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "result": {
    "type": "text",
    "text": "Result as JSON or markdown"
  }
}

See MCP Tools Reference for complete tool documentation.

Rate Limiting

API endpoints are rate-limited per token:

Resource Limit Window
Search 30 1 minute
Memory Create 10 1 minute
List Operations 60 1 minute
Other Endpoints 100 1 minute

Rate limit headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1643817000

When rate limited, response is 429 with Retry-After header.

Pagination

List endpoints support pagination with limit and offset:

# Get first 50
curl "https://fold.example.com/api/projects/my-app/memories?limit=50&offset=0"

# Get next 50
curl "https://fold.example.com/api/projects/my-app/memories?limit=50&offset=50"

Response includes:

{
  "memories": [...],
  "total": 5432,
  "limit": 50,
  "offset": 0
}

Clone this wiki locally