API Documentation

Every example below runs against http://localhost:3000 — this very instance. Create a key first (step 1) and substitute it. All state you touch is real: bytes go to real nodes, jobs run on real CPUs.

1 · Accounts

POST/api/v1/keys

Create an account + API key. No signup, no email.

curl -s -X POST http://localhost:3000/api/v1/keys -H "Content-Type: application/json" -d '{"name":"me"}'

2 · The Grid (public, no key needed)

GET/api/v1/grid/stats

Live grid totals — nodes, cores, per-tier capacity, ops/sec, p50/p99 latency.

curl -s http://localhost:3000/api/v1/grid/stats

GET/api/v1/grid/nodes

Every connected node with its real contribution.

curl -s http://localhost:3000/api/v1/grid/nodes

3 · The Memory — alloc / write / read / free

POST/api/v1/mem/alloc

Allocate space. tier: auto | accel | dram | cxl | nvme. Chunks are placed on two distinct nodes (replication factor 2). tier=auto allocations are MemoryOS-managed: promoted up the ladder while hot, physically migrated down while idle.

curl -s -X POST http://localhost:3000/api/v1/mem/alloc \
  -H "Authorization: Bearer om_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bytes": 1048576, "tier": "auto", "name": "hello"}'

PUT/api/v1/mem/:allocId

Write raw bytes (any binary body). Response reports measured latency and which nodes stored your data.

curl -s -X PUT http://localhost:3000/api/v1/mem/ALLOC_ID \
  -H "Authorization: Bearer om_YOUR_KEY" \
  --data-binary "hello from the one machine"

GET/api/v1/mem/:allocId

Read your bytes back. Headers carry the truth: X-OM-Latency-Ms, X-OM-Served-By, X-OM-Tier. Add ?meta=1 for JSON metadata instead of the body.

curl -s -D - http://localhost:3000/api/v1/mem/ALLOC_ID \
  -H "Authorization: Bearer om_YOUR_KEY" -o out.bin

DELETE/api/v1/mem/:allocId

Free the allocation on every replica.

curl -s -X DELETE http://localhost:3000/api/v1/mem/ALLOC_ID -H "Authorization: Bearer om_YOUR_KEY"

POST/api/v1/mem/:allocId/attest

Proof of possession: every replica node must return sha256(salt ‖ chunkData), computed on its own hardware. Verify against hashes you compute from bytes YOU hold — a node that doesn't store your data cannot answer, and the random salt makes caching impossible. Writes also return a sha256 receipt; reads carry X-OM-SHA256.

curl -s -X POST http://localhost:3000/api/v1/mem/ALLOC_ID/attest \
  -H "Authorization: Bearer om_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"salt": "'$(openssl rand -base64 16)'"}'

4 · Jobs — distributed compute

POST/api/v1/jobs

kinds: wordcount {text | allocId}, hashsearch {prefix, zeros, range}, primecount {from, to}. Sharded across nodes by core count.

curl -s -X POST http://localhost:3000/api/v1/jobs \
  -H "Authorization: Bearer om_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "primecount", "params": {"from": 2, "to": 10000000}}'

GET/api/v1/jobs/:jobId

Job status with per-node task progress, reported live by the nodes.

curl -s http://localhost:3000/api/v1/jobs/JOB_ID -H "Authorization: Bearer om_YOUR_KEY"

5 · MemoryOS — automatic placement

GET/api/v1/memoryos

Live migration feed: every promote/demote/evict event with bytes moved, elapsed ms, and real price delta. No key needed.

curl -s http://localhost:3000/api/v1/memoryos

6 · The Reserve — capacity as an asset

POST/api/v1/reserve

Reserve gb × hours of a tier — the balance is held in GB-seconds and drawn down against metered usage. Rejected with HTTP 409 if it exceeds truthfully-reservable capacity.

curl -s -X POST http://localhost:3000/api/v1/reserve \
  -H "Authorization: Bearer om_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier": "dram", "gb": 0.1, "hours": 24}'

GET/api/v1/reserve

Your reservations, live GB-second balances, drawdown ledger, and current usage.

curl -s http://localhost:3000/api/v1/reserve -H "Authorization: Bearer om_YOUR_KEY"

POST/api/v1/reserve/:id/activate

Emergency release — Fort Knox opens. The reservation's capacity becomes guaranteed: if the tier is full, unreserved tenants are evicted (each eviction is a ledger entry) so your allocations always fit.

curl -s -X POST http://localhost:3000/api/v1/reserve/RESERVATION_ID/activate -H "Authorization: Bearer om_YOUR_KEY"

Full loop in 60 seconds

KEY=$(curl -s -X POST http://localhost:3000/api/v1/keys -d '{"name":"demo"}' | grep -o '"om_[^"]*"' | tr -d '"')
ID=$(curl -s -X POST http://localhost:3000/api/v1/mem/alloc -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"bytes":1048576}' | grep -o '"m_[^"]*"' | tr -d '"' | head -1)
curl -s -X PUT http://localhost:3000/api/v1/mem/$ID -H "Authorization: Bearer $KEY" --data-binary "it is all real"
curl -s http://localhost:3000/api/v1/mem/$ID -H "Authorization: Bearer $KEY"