Quickstart

1. Issue a workspace API token

Sign in to Shelvia and open Settings → API. Create a token with the scopes you need (memory.read for reads, memory.context for context packs, memory.candidates for writes). Copy the token once, it is only shown at creation.

Tokens are bound to a single workspace audience. They cannot read or write across workspaces.

2. Read project context

Every read response carries provenance, workspace_id, project_id, generated_at, api_version.

curl -s "https://shelvia.net/api/v1/project-memory/projects/$PROJECT_ID/context" \
  -H "Authorization: Bearer $SHELVIA_TOKEN" | jq .

3. Search reviewed memory

Hybrid keyword + vector search across decisions, sources, prompts, candidates, and summaries. Workspace-scoped at every layer.

curl -s -X POST "https://shelvia.net/api/v1/project-memory/search" \
  -H "Authorization: Bearer $SHELVIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did we decide about pricing?",
    "project_id": "'"$PROJECT_ID"'",
    "mode": "hybrid",
    "limit": 10
  }' | jq .

4. Generate a context pack

Ranked structured context for the next session. Seven composite signals blend structured priority, source-backing, health, semantic similarity, recency, purpose match, and kind weight.

curl -s -X POST "https://shelvia.net/api/v1/project-memory/projects/$PROJECT_ID/context-pack" \
  -H "Authorization: Bearer $SHELVIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Continue the v2 launch checklist",
    "target_tool": "claude",
    "max_chars": 12000,
    "semantic_ranking": true
  }' | jq .

5. Create a review candidate (write)

Writes always create review candidates, never trusted memory directly. A workspace member approves before the row enters trusted memory.

curl -s -X POST "https://shelvia.net/api/v1/project-memory/projects/$PROJECT_ID/candidates" \
  -H "Authorization: Bearer $SHELVIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "decision",
    "title": "Use Paystack for African card payments",
    "content": "We chose Paystack because…",
    "source_url": "https://example.com/source"
  }' | jq .

Where to go next

• Auth: scopes, OAuth, extension tokens, /docs/developers/auth
• MCP: tool catalog and transport, /docs/developers/mcp
• Webhooks: subscribe to memory events, /docs/developers/webhooks
• Concepts: how memory is structured, /docs/concepts/project-memory