REST API

Everything innernet stores is reachable over plain REST at https://innernet.live/api/v1. Three resource families:

Context — projects → dimensions → captures: the structured world-model innernet maintains.
Versioning — commits, branches, diff, merge: fork an idea-space, evolve it in isolation, fold it back. The part no flat memory store can do.
Memories — a flat, namespaced store for apps you build: scope rows to your own end-users, agents, and runs.

Plus ranked full-text search across all of it, and the owner's Self Map behind disclosure gates. The machine-readable spec lives at /api/v1/openapi.json.

authentication#

Mint an API key at innernet.live/developers. Keys are shown once, stored hashed, carry read and/or write scopes, and can be revoked individually (up to 10 active keys).

bash

curl https://innernet.live/api/v1/projects \
  -H "Authorization: Bearer innernet_..."

OAuth 2.1 access tokens (the ones MCP clients hold) work on every endpoint too.

add and recall memories#

bash

# remember something about one of YOUR users
curl -X POST https://innernet.live/api/v1/memories \
  -H "Authorization: Bearer innernet_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Prefers concise answers; works in TypeScript.",
    "user_id": "user_42",
    "tags": ["preference"]
  }'

# recall them later
curl "https://innernet.live/api/v1/memories?user_id=user_42&limit=20" \
  -H "Authorization: Bearer innernet_..."

user_id, agent_id, and run_id are your namespaces — innernet keeps each end-user's memories separate under your account. metadata is free-form JSON; tags are filterable.

search everything#

bash

curl "https://innernet.live/api/v1/search?q=pricing+decision" \
  -H "Authorization: Bearer innernet_..."

One query ranks across dimensions, nodes, captures, projects, and memories, returning highlighted snippets with kind + ref so you can fetch the source. Scope to one project with &project=slug.

read and write context#

bash

# the full map
curl https://innernet.live/api/v1/projects/my-product \
  -H "Authorization: Bearer innernet_..."

# one dimension
curl https://innernet.live/api/v1/projects/my-product/dimensions/roadmap \
  -H "Authorization: Bearer innernet_..."

# replace it (writes a commit)
curl -X PUT https://innernet.live/api/v1/projects/my-product/dimensions/roadmap \
  -H "Authorization: Bearer innernet_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "# Roadmap\n\n- ship v1", "commit_message": "trim roadmap"}'

# append a capture (consolidated into dimensions on next sync)
curl -X POST https://innernet.live/api/v1/projects/my-product/captures \
  -H "Authorization: Bearer innernet_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "Decided: usage-based pricing.", "tags": ["decision"]}'

version everything: commits & branches#

This is the part no other memory API has. Every save and capture is a commit; a branch forks the whole context map so two versions of an idea can exist at once — then diff and merge when a direction wins.

bash

# history
curl https://innernet.live/api/v1/projects/my-product/commits \
  -H "Authorization: Bearer innernet_..."

# fork the map at its current head
curl -X POST https://innernet.live/api/v1/projects/my-product/branches \
  -H "Authorization: Bearer innernet_..." -H "Content-Type: application/json" \
  -d '{"name": "pricing-experiment", "summary": "what if usage-based?"}'

# work on the branch — trunk untouched
curl -X PUT https://innernet.live/api/v1/projects/my-product/branches/pricing-experiment/dimensions/pricing \
  -H "Authorization: Bearer innernet_..." -H "Content-Type: application/json" \
  -d '{"content": "# Pricing\n\nUsage-based, $0.005/1k ops."}'

# what changed vs trunk?
curl https://innernet.live/api/v1/projects/my-product/branches/pricing-experiment/diff \
  -H "Authorization: Bearer innernet_..."

# the experiment won — fold it back (records a merge commit, bumps head)
curl -X POST https://innernet.live/api/v1/projects/my-product/branches/pricing-experiment/merge \
  -H "Authorization: Bearer innernet_..."

Not ready to decide? PATCH the branch with {"status": "parked"} — it's archived with its overlay intact, revivable any time. Merge semantics are branch-wins (same as the CLI); conflict-aware merge is on the roadmap.

personal memory over the API#

The account owner's Self Map — atomic facts with disclosure classes — is readable and writable with the same key. private facts never cross the API, whatever ceiling you ask for.

bash

# facts up to a disclosure ceiling (self | trusted | work | public)
curl "https://innernet.live/api/v1/self/facts?max_disclosure=work" \
  -H "Authorization: Bearer innernet_..."

# queue a fact-candidate (the consolidator distills it on next sync)
curl -X POST https://innernet.live/api/v1/self/capture \
  -H "Authorization: Bearer innernet_..." -H "Content-Type: application/json" \
  -d '{"content": "Prefers dark mode everywhere.", "dimension_hint": "preferences"}'

And any project load can carry the owner's context with it — GET /v1/projects/{slug}?include_self=1 appends a disclosure-gated personal_context slice, so an app you build knows how you work the moment it loads what you're working on.

errors & rate limits#

Every error is one shape:

json

{ "error": { "code": "not_found", "message": "Project not found: my-product" } }

status	code	meaning
401	`unauthorized`	Missing/invalid bearer token
403	`insufficient_scope`	Key lacks `read` or `write`
404	`not_found`	Resource doesn't exist (or isn't yours)
400	`invalid_body` / `invalid_query`	Malformed request
429	`rate_limited`	Over 300 req/min — honor `Retry-After`

CORS is open (Access-Control-Allow-Origin: *), so browser apps work — but never ship a write-scoped key to a browser; mint a read-only key instead.

endpoint reference#

GET/v1/projectsList projects

All context maps owned by the caller, most recently updated first.

GET/v1/projects/{slug}Load a context map

The full map: manifest, every dimension (markdown), every node, recent commits, and the per-project capture protocol.

parameters

`slug`	path · required	string
`include_self`	query	Append a disclosure-gated slice of the account owner's Self Map (personal_context)

GET/v1/projects/{slug}/dimensions/{name}Read a dimension

parameters

`slug`	path · required	string
`name`	path · required	string

PUT/v1/projects/{slug}/dimensions/{name}Create or replace a dimension

Replaces the dimension body and writes a commit to the project history.

parameters

`slug`	path · required	string
`name`	path · required	string

body

`content`	string · required	Full markdown body
`commit_message`	string

DELETE/v1/projects/{slug}/dimensions/{name}Delete a dimension

Removes the dimension and records the deletion in the commit log.

parameters

`slug`	path · required	string
`name`	path · required	string

POST/v1/projects/{slug}/capturesCapture into a project

Append a note/decision/insight to the project commit log. The background consolidator folds captures into dimensions on the next sync.

parameters

slug path · required string

body

`content`	string · required
`tags`	array

GET/v1/memoriesList memories

parameters

`user_id`	query	string
`agent_id`	query	string
`run_id`	query	string
`project`	query	string
`tag`	query	string
`limit`	query	integer
`offset`	query	integer

POST/v1/memoriesAdd a memory

Store a memory scoped to your application. Namespace it with user_id / agent_id / run_id to keep each of your end-users’ memories separate.

body

`content`	string · required
`user_id`	string	Your end-user id
`agent_id`	string
`run_id`	string
`project`	string	Optional innernet project slug to associate
`metadata`	object
`tags`	array

GET/v1/memories/{id}Get a memory

parameters

id path · required string

PATCH/v1/memories/{id}Update a memory

parameters

id path · required string

body

`content`	string
`metadata`	object
`tags`	array

DELETE/v1/memories/{id}Delete a memory

parameters

id path · required string

GET/v1/projects/{slug}/commitsList commits

The project's append-only history, newest first — every save, capture, sync, and merge.

parameters

`slug`	path · required	string
`limit`	query	integer
`offset`	query	integer

GET/v1/projects/{slug}/commits/{hash}Get a commit

One commit with its full diff payload (capture content, merge diffs).

parameters

`slug`	path · required	string
`hash`	path · required	string

GET/v1/projects/{slug}/branchesList branches

parameters

slug path · required string

POST/v1/projects/{slug}/branchesFork a branch

Fork the context map at its current head. The branch gets a full snapshot (overlay) of trunk dimensions + nodes; trunk stays untouched until merge.

parameters

slug path · required string

body

`name`	string · required	Branch name (slug-like)
`summary`	string

GET/v1/projects/{slug}/branches/{name}Get a branch

parameters

`slug`	path · required	string
`name`	path · required	string

PATCH/v1/projects/{slug}/branches/{name}Park / unpark a branch

status "parked" archives without merging (overlay preserved); "active" revives.

parameters

`slug`	path · required	string
`name`	path · required	string

body

status string · required

GET/v1/projects/{slug}/branches/{name}/diffDiff branch vs trunk

added / modified / removed / unchanged for dimensions and nodes.

parameters

`slug`	path · required	string
`name`	path · required	string

POST/v1/projects/{slug}/branches/{name}/mergeMerge a branch

Apply the branch to trunk (branch wins; removed-in-branch deletes from trunk), record a merge commit, bump the head, mark the branch merged.

parameters

`slug`	path · required	string
`name`	path · required	string

GET/v1/projects/{slug}/branches/{name}/dimensions/{dim}Read a branch dimension

parameters

`slug`	path · required	string
`name`	path · required	string
`dim`	path · required	string

PUT/v1/projects/{slug}/branches/{name}/dimensions/{dim}Write a dimension into a branch

Edits the branch overlay only — trunk is untouched until merge.

parameters

`slug`	path · required	string
`name`	path · required	string
`dim`	path · required	string

body

content string · required Full markdown body

DELETE/v1/projects/{slug}/branches/{name}/dimensions/{dim}Remove a dimension from a branch

Merging afterwards deletes it from trunk.

parameters

`slug`	path · required	string
`name`	path · required	string
`dim`	path · required	string

GET/v1/projects/{slug}/artifactsList artifacts

The project's live auto-maintained documents.

parameters

slug path · required string

GET/v1/projects/{slug}/artifacts/{id}Read an artifact

parameters

`slug`	path · required	string
`id`	path · required	string

GET/v1/self/factsRead Self Map facts

The account owner's Personal Memory, gated by disclosure ceiling. `private` never crosses the API regardless of the requested ceiling.

parameters

`dimension`	query	string
`max_disclosure`	query	string

POST/v1/self/captureCapture a Self candidate

Queue a fact-candidate about the account owner; the consolidator distills it on next sync.

body

`content`	string · required
`dimension_hint`	string
`project_context`	string

GET/v1/self/statusSelf Map status

GET/v1/searchSearch everything

Ranked full-text search across dimensions, nodes, captures, projects, and memories, with highlighted snippets.

parameters

`q`	query · required	string
`project`	query	Limit to one project slug
`limit`	query	integer