API Reference

The MindGraph Cloud API combines graph primitives, cognitive-layer endpoints, scoped-corpus synthesis, and managed autonomous agents.

Base URL: https://api.mindgraph.cloud. All authenticated endpoints require a Bearer token (API key or JWT) in the Authorization header.

Errors

All error responses return a JSON body with an error field and optionally a code field for programmatic handling.

// Error response format
{ "error": "descriptive message", "code": "error_code" }

Pagination

List endpoints (GET /nodes, POST /retrieve with layer/recent) support pagination via limit and offset parameters.

// Query params (GET) or body fields (POST)
{ "limit": 100, "offset": 0 }

// Paginated response
{ "items": [...], "has_more": true }

Health

Authentication

Management

Billing

CRUD Layer (~59 routes)

Standard graph operations — create, read, update, delete nodes and edges.

Stats

Generic Node CRUD

// Request
{
  "label": "User prefers dark mode",    // required
  "node_type": "Preference",            // optional (inferred from props._type)
  "summary": "Dark mode preference",    // optional
  "props": {                            // optional - NodeProps (serde-tagged)
    "_type": "Preference",
    "key": "theme",
    "value": "dark"
  },
  "agent_id": "my-agent"               // optional (defaults to server default)
}

// Response (201 Created)
{
  "uid": "abc123",
  "label": "User prefers dark mode",
  "summary": "Dark mode preference",
  "node_type": "Preference",
  "layer": "memory",
  "confidence": 0.5,
  "salience": 0.5,
  "props": { "_type": "Preference", "key": "theme", "value": "dark" },
  "created_at": 1709750400.0,
  "updated_at": 1709750400.0,
  "tombstone_at": null,
  "version": 1
}

Edge CRUD

Search & Filter

// Request
{
  "query": "dark mode",     // required - search text
  "node_type": "Preference", // optional - filter by type
  "layer": "memory",        // optional - filter by layer
  "limit": 10               // optional (default 100)
}

// Response (array of SearchResult)
[
  {
    "uid": "abc123",
    "label": "User prefers dark mode",
    "summary": "Dark mode preference",
    "node_type": "Preference",
    "score": 0.95
  }
]

Traversal

Agent & Entity

Lifecycle

Embeddings

Batch Operations

Epistemic Queries

Cognitive Endpoints (18 routes)

Cognitive endpoints are the primary way to interact with MindGraph. Each endpoint accepts an action field that selects the operation, and creates the right node type with proper edges and metadata automatically. Use these instead of the generic CRUD endpoints whenever possible — they ensure your data is correctly structured and connected.

For example, instead of creating a bare Claim node via POST /node, use POST /epistemic/argument to create a claim with evidence, warrant, and linking edges in a single call. This produces a richer, more useful knowledge graph.

Reality Layer

Capture external information — sources, snippets, observations — and manage entity identity. The Reality layer includes first-class types for Person, Organization, Nation, Event, Place, and Concept, with Entity serving as a fallback for other named things (technologies, products, etc.).

Epistemic Layer

Build structured knowledge — claims with evidence, hypotheses, theories, concepts, patterns, and formal structures.

Intent Layer

Track goals, projects, milestones, and structured decision-making.

Action Layer

Model workflows, procedures, affordances, and risk assessments.

Memory Layer

Manage sessions, traces, journal entries, summaries, preferences, and memory policies.

Agent Layer

Plan tasks, govern agent behavior, and track execution lifecycle. These are the cognitive-layer agent primitives (graph nodes for plans, policies, executions). For managed autonomous agents, see Agents and the /v1/agents/* section below.

Cross-cutting

Retrieve, traverse, and evolve the graph.

Ingestion & Retrieval

Chunk-based document ingestion with automatic LLM extraction. Documents default to Reality + Epistemic (2 passes); single chunks to Reality + Epistemic + Memory (3 passes); session transcripts to Reality + Epistemic + Intent + Action + Memory (5 passes). Callers can override via the layers parameter. Requires OPENAI_API_KEY to be configured on the server.

# Ingest a single chunk (synchronous)
curl -X POST /ingest/chunk \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Einstein developed general relativity in 1915...",
    "layers": ["reality", "epistemic"]
  }'

# Response:
# { "chunk_uid": "...", "nodes_created": 13, "edges_created": 23, ... }

# Ingest a full document (async — returns job ID)
curl -X POST /ingest/document \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Chapter 1: ...",
    "title": "My Document",
    "document_type": "article"
  }'

# Response: { "job_id": "...", "document_uid": "..." }

# Poll job status
curl /jobs/<job_id>

# Retrieve context with semantic search
curl -X POST /retrieve/context \
  -H "Content-Type: application/json" \
  -d '{ "query": "What did Einstein discover?", "node_limit": 10, "article_limit": 3 }'

Projects & Synthesis

Scoped-corpus synthesis: mine cross-document signals for a Project node and turn the top idea clusters into Article nodes. See the Projects guide for concepts and examples.

Managed Agents

Cloud-only endpoints for managing autonomous research agents (Pro plan and higher). These live under /v1/agents/* and are hosted by mindgraph-cloud, not the graph API. See the Agents guide for a full walkthrough.

Node Props Reference

Every node type has a typed props object. When using cognitive endpoints, pass these fields inside the props field of the request body. All fields are optional unless noted.

Reality Layer

Epistemic Layer

Intent Layer

Action Layer

Memory Layer

Agent Layer