API

The Neutron AI API lets your platform remember, recall, connect temporal knowledge, assemble bounded context, compare decisions, predict consequences, record outcomes, review learning, and manage scoped intelligence for agents.

All authenticated requests use:

Authorization: Bearer <NEUTRON_API_TOKEN>

Base URL

https://neutronai.dev/api

Use your assigned API base URL if your workspace has a custom endpoint.

Response shape

Successful responses return an object with success: true and a data payload.

Errors return success: false with a stable error code and human-readable message.

{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "Human-readable message"
  }
}

Memory endpoints

• GET /v1/nuclei
• POST /v1/nuclei
• GET /v1/nuclei/:nucleusId
• POST /v1/memory/remember
• POST /v1/memory/recall
• POST /v1/memory/agent-context
• POST /v1/memory/forget
• GET /v1/memory/audit
• POST /v1/memory/compact

Cache endpoints

• GET /v1/memory/cache/stats
• POST /v1/memory/cache/invalidate
• POST /v1/memory/cache/warm

Agent endpoints

• POST /v1/memory/reflect
• POST /v1/memory/skills/learn
• POST /v1/memory/kb/upsert

Consequence endpoints

• POST /v1/consequence/plan
• POST /v1/consequence/decide
• POST /v1/consequence/observe
• POST /v1/consequence/reflect
• POST /v1/consequence/delete
• POST /v1/consequence/delete-scoped

Use the Consequence decision-support guide for generic adapters and versioned application-supplied candidates.

Knowledge graph endpoints

• POST /v1/entities/upsert
• POST /v1/entities/search
• GET /v1/entities/:entityId
• POST /v1/entities/tombstone
• POST /v1/relationships/upsert
• GET /v1/relationships/:relationshipId
• POST /v1/relationships/tombstone
• POST /v1/graph/neighbours
• POST /v1/graph/query
• POST /v1/claims
• GET /v1/contradictions
• POST /v1/contradictions/resolve

Context and identity endpoints

• POST /v1/context/build
• POST /v1/search
• POST /v1/agents/upsert
• GET /v1/agents/:agentId
• POST /v1/snapshots
• GET /v1/snapshots/:snapshotId

Decision, outcome, and simulation endpoints

• POST /v1/decisions
• GET /v1/decisions/:decisionId
• POST /v1/decisions/evaluate
• POST /v1/consequences/predict
• POST /v1/outcomes
• POST /v1/learning/review
• POST /v1/simulations

See Knowledge and decision intelligence for provenance, bitemporal reads, graph dimensions, permissions, snapshots, Pareto guidance, solver boundaries, counterfactuals, and reviewed learning.

MCP endpoints

• POST /mcp
• GET /mcp/tools

MCP tools expose the main memory, entity, graph, context, decision, consequence, outcome, and simulation workflows through a compact schema-compatible interface for agent clients.

Required fields

Most intelligence requests include:

• nucleusId: the memory-bank boundary
• scopeId or scopeIds: the user, project, team, agent, or session boundary
• agentId: the calling agent or integration
• task, query, text, or a structured domain object: the external workflow input

Knowledge writes also carry confidence and provenance. Temporal reads can include validAt and knowledgeAt so applications can distinguish what was true from what Neutron had recorded at the time.

tenantId remains a legacy alias for nucleusId. If both are supplied, they must match.

Workspace API keys can create Nuclei and access Nuclei linked to that workspace. Nucleus access tokens can access only their own Nucleus. Prefer Nucleus tokens for runtime memory calls.

Safe usage

Do not send provider API keys, session cookies, private credentials, hidden prompts, raw chain-of-thought, or unnecessary regulated data. Apply persistent agent permissions during context retrieval and keep high-risk actions behind human approval.