API explorer

Know the shape before you wire it.

Memorylayer exposes plain HTTP endpoints for service discovery, workspace memory, ingestion, and the hosted MCP bridge. These fixtures show the contract without needing a live key.

Fixture JSON OpenAPI Create workspace

request and response fixtures

auth modes: public discovery and workspace key

HTTP

no required vendor SDK or local daemon

discover ingest recall handoff

01 / Discover

Read public manifests

Start with service, capability, MCP, SDK, playbook, and fixture JSON before wiring a client.

02 / Ingest

Import useful state

Use batch ingest for notes, reports, transcripts, and handoffs that should become workspace memory.

03 / Recall

Query before work

Call search, recent memory, or `recall_context` so agents start with relevant prior state.

04 / Handoff

Write the result

Store decisions, project updates, negative knowledge, and checkpoints through the bridge.

PublicManifest, capabilities, examples, and MCP tool catalog.

PrivateWorkspace memory routes require a workspace API key.

BridgeUse { tool, args } for the hosted MCP-compatible call path.

Request fixtures

These examples are stable enough for docs, generated clients, and agent setup screens.

Use JSON

GET public

Service status

Check whether the hosted service is alive and read public counts.

/api/service/status

No request body

{
  "capabilities": 230,
  "database": "postgres",
  "engram_source_revision": "bec09d48858fcac554648410285e793131f2c915",
  "features": 29,
  "mcp_tools": 83,
  "runtime": "vps",
  "service": "memorylayer",
  "source_revision": "fa96793e9d10cfb77dcfc89ff1aeffe9e8988b0e",
  "status": "ok"
}

GET public

Service manifest

Load the route map and public integration counts for client setup screens.

/api/service/manifest

No request body

{
  "counts": {
    "api_examples": 12,
    "capabilities": 250
  },
  "routes": {
    "api_examples": "https://memorylayer.run/api/examples",
    "docs": "https://memorylayer.run/docs",
    "mcp_manifest": "https://memorylayer.run/api/mcp/manifest"
  },
  "service": "memorylayer"
}

GET public

Service architecture

Read the concrete runtime, storage, model, limit, and surface contract.

/api/service/architecture

No request body

{
  "models": {
    "embedding_dimensions": 384,
    "embedding_model": "BAAI/bge-small-en-v1.5"
  },
  "runtime": {
    "framework": {
      "name": "FastAPI"
    },
    "python": "3.12"
  },
  "service": {
    "name": "Memorylayer",
    "version": "0.3.0"
  },
  "storage": {
    "metadata_database": "postgres",
    "workspace_backend": "postgres"
  }
}

GET public

Service readiness

Run bounded checks for database, runtime cache, security posture, and public surface wiring.

/api/service/readiness

No request body

{
  "checks": [
    {
      "name": "database",
      "status": "pass"
    },
    {
      "name": "runtime_cache",
      "status": "pass"
    },
    {
      "name": "public_surface",
      "status": "pass"
    }
  ],
  "status": "ok"
}

GET public

MCP manifest

Discover grouped tools, auth headers, and workspace bridge URL templates.

/api/mcp/manifest

No request body

{
  "auth": [
    "Authorization: Bearer \u003cworkspace-api-key\u003e",
    "X-API-Key: \u003cworkspace-api-key\u003e"
  ],
  "tool_groups": [
    {
      "name": "Retrieval",
      "tools": [
        {
          "name": "recall_context"
        }
      ]
    }
  ],
  "transport": "http-json",
  "workspace_call_url_template": "https://memorylayer.run/api/workspaces/{slug}/mcp"
}

GET workspace key

Workspace bootstrap

Fetch workspace-specific URLs, headers, starter skills, and tool discovery.

/api/workspaces/{slug}/bootstrap

No request body

{
  "auth": {
    "headers": [
      "Authorization: Bearer \u003cworkspace-api-key\u003e",
      "X-API-Key: \u003cworkspace-api-key\u003e"
    ]
  },
  "endpoints": {
    "mcp": "https://memorylayer.run/api/workspaces/demo/mcp"
  },
  "skills": [
    {
      "name": "workspace-memory"
    }
  ],
  "workspace": {
    "slug": "demo"
  }
}

GET workspace key

Connection kit

Return a normalized client profile with endpoints, MCP config, skills, and startup calls.

/api/workspaces/{slug}/connect

No request body

{
  "endpoints": {
    "mcp": "https://memorylayer.run/api/workspaces/demo/mcp"
  },
  "service": {
    "base_url": "https://memorylayer.run",
    "name": "Memorylayer"
  },
  "startup_calls": [
    {
      "method": "GET",
      "name": "bootstrap"
    }
  ],
  "workspace": {
    "slug": "demo"
  }
}

GET workspace key

Env template

Return a plain text env block for local scripts, workers, and agent launchers.

/api/workspaces/{slug}/env

No request body

{
  "text": "MEMORYLAYER_URL=\"https://memorylayer.run\"\nMEMORYLAYER_WORKSPACE=\"demo\"\nMEMORYLAYER_KEY=\"engram_...\""
}

GET workspace key

Agent config bundle

Fetch Codex profile text, Claude skill markdown, env output, curl setup commands, and endpoint URLs.

/api/workspaces/{slug}/agent-config

No request body

{
  "claude_skill": "---\nname: memorylayer-demo",
  "codex_toml": "[memorylayer]\nworkspace = \"demo\"",
  "curl": {
    "bootstrap": "curl -H \"Authorization: Bearer engram_...\" ..."
  },
  "workspace": {
    "slug": "demo"
  }
}

POST workspace key

Ingest preview

Preview how a payload will split before writing anything to memory.

/api/workspaces/{slug}/ingest/preview

{
  "content": "# One\nalpha\n# Two\nbeta",
  "split_mode": "markdown"
}

{
  "ingest_preview": {
    "item_count": 2
  },
  "split_mode": "markdown",
  "workspace": "demo"
}

POST workspace key

Recall context

Ask the bridge for compact context before an agent starts work.

/api/workspaces/{slug}/mcp

{
  "args": {
    "max_tokens": 1200,
    "query": "current project state"
  },
  "tool": "recall_context"
}

{
  "ok": true,
  "result": "Relevant memory context...",
  "tool": "recall_context"
}

POST workspace key

Session checkpoint

Save a compact handoff after meaningful work or deployment.

/api/workspaces/{slug}/mcp

{
  "args": {
    "limit": 8,
    "note": "Shipped API explorer"
  },
  "tool": "session_checkpoint"
}

{
  "ok": true,
  "result": {
    "saved": true
  },
  "tool": "session_checkpoint"
}

POST workspace key

Batch ingest

Import notes, transcripts, reports, or pipeline output as memories.

/api/workspaces/{slug}/ingest

{
  "items": [
    "Release deployed",
    "Next: test onboarding"
  ],
  "memory_type": "fact",
  "source_name": "handoff.md",
  "source_type": "handoff"
}

{
  "memory_ids": [
    "mem_1",
    "mem_2"
  ],
  "ok": true,
  "run": {
    "items": 2,
    "source_name": "handoff.md"
  }
}

GET workspace key

Usage feed

Read recent API calls, per-route totals, and key activity.

/api/workspaces/{slug}/usage

No request body

{
  "recent_events": [
    {
      "route": "/api/workspaces/demo/mcp",
      "status_code": 200
    }
  ],
  "route_counts": [
    {
      "count": 14,
      "route": "/api/workspaces/demo/mcp"
    }
  ]
}

GET workspace key

Observability

Read latency, failure rate, slow routes, top routes, runtime cache, and recent ingest runs.

/api/workspaces/{slug}/observability

No request body

{
  "observability": {
    "failure_rate": 0,
    "p95_duration_ms": 14.2,
    "top_routes": [
      {
        "route": "/mcp"
      }
    ]
  },
  "workspace": "demo"
}

GET workspace key

Recent export

Export the latest workspace memories for backup, inspection, or migration checks.

/api/workspaces/{slug}/export/recent

No request body

{
  "memories": [
    {
      "content": "API explorer deployed",
      "layer": "episodic",
      "memory_type": "fact"
    }
  ],
  "workspace": "demo"
}

POST workspace key

Error shape

All service errors return a direct detail message that clients can show or log.

/api/workspaces/{slug}/mcp

{
  "args": {},
  "tool": "unknown_tool"
}

{
  "detail": "Unsupported tool: unknown_tool"
}

Client rule

Start with `/api/service/manifest`, then choose either direct workspace routes or the MCP bridge. Keep workspace keys server-side when possible.