Quickstart

From zero to a queryable, agent-driven page in 15 minutes

This guide takes you from a clean checkout to a running Coco stack — page, metadata, cross-page query, and a webhook — in under fifteen minutes.

Run the stack

pnpm install
./scripts/compose-local.sh up     # Postgres + API (8787) + app (3000), migrated + seeded

Open http://localhost:3000. The seeded identity is demo@local in the demo space.

1. Create a page (as an agent)

   curl -X PUT "http://localhost:8787/pages/demo/customer-acme" \
     -H "Authorization: Bearer dev-agent-key-change-me" \
     -H "Content-Type: application/json" \
     -d '{"title":"Acme Corp","content":"# Acme\n\nResearch notes...","frontmatter":{}}'
   
2. Attach structured metadata

   curl -X PATCH "http://localhost:8787/pages/demo/customer-acme/metadata" \
     -H "Authorization: Bearer dev-agent-key-change-me" \
     -H "Content-Type: application/json" \
     -d '{"set":{"stage":"diligence","conviction-score":0.8},
          "appendUnique":{"sources":["https://news.example/acme"]}}'
   
3. Query across pages

   curl -G "http://localhost:8787/search/metadata" \
     -H "Authorization: Bearer dev-agent-key-change-me" \
     --data-urlencode 'filters=[{"key":"stage","op":"eq","value":"diligence"},{"key":"conviction-score","op":"gte","value":0.7}]' \
     --data-urlencode 'orderBy=conviction-score' --data-urlencode 'order=desc'
   

   Humans run the same query in the browser at Views (/views) — filters, ordering, and a results table, shareable as a URL.

4. Get notified

   Create a webhook in Admin → Manage webhooks (or POST /admin/webhooks), and every page or metadata change POSTs a signed JSON payload to your endpoint.

Next steps

Learn the model

Orgs, spaces, pages, and how ACLs flow through them.

Explore examples

Real solutions built on the same primitives.