Skip to main content
The workspace is a git folder of Markdown — knowledge, plans, and the agent’s session, all just files with no dictated structure. Every workspace route derives your identity from the API key; you never pass a subject.

​
Browse and read

# the file tree
curl -H "X-API-Key: $API_KEY" "$API_BASE/agent/workspace/tree"
# → { "files": ["kg/entities/acme.md", "meetings/2026-06-29-acme.md", ...] }

# one file's content (404 if absent)
curl -H "X-API-Key: $API_KEY" "$API_BASE/agent/workspace/file?path=kg/entities/acme.md"
# → { "path": "...", "content": "..." }

# git state — branch, uncommitted changes, recent commits
curl -H "X-API-Key: $API_KEY" "$API_BASE/agent/workspace/git"
Pass hidden=true to tree to include dotfiles. git is the durable state and the undo — every agent write is a commit.

​
Upload documents

Add files to the workspace so agents can ground on them (multipart; ≤25 MB each): 
curl -X POST "$API_BASE/agent/workspace/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "files=@./contract.pdf" -F "files=@./notes.md"
# → { "files": [ { "name": "contract.pdf", "path": "..." }, ... ] }

​
Initialize a fresh workspace

Idempotent — seeds the workspace if it doesn’t exist yet: 
curl -X POST "$API_BASE/agent/workspace/init" -H "X-API-Key: $API_KEY"
# → 201 { "workspace": "...", "seeded": true, "already_initialized": false }

​
Attach your own git repo

Swap in an external git repo as the active workspace — the current one is parked, not lost: 
curl -X POST "$API_BASE/agent/workspace/swap" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"repo":"https://github.com/acme/knowledge.git","ref":"main","token":"<git-token>"}'
Omit repo to swap back to the seed workspace. Check what’s attached: 
curl -H "X-API-Key: $API_KEY" "$API_BASE/agent/workspace/attached"
# → { "active": {...}, "parked": [...] }

​
Next

Put an agent to work on what’s here — chat with the workspace or run an unattended routine over it.