REST API

All API routes require Authorization: Bearer <api-key>.

What this page covers

Core endpoint groups for entities, search, tasks, sync, graph, and queue status.

Reference

Entity endpoints

• POST /api/entities
• GET /api/entities/:id
• PATCH /api/entities/:id
• DELETE /api/entities/:id
• GET /api/entities with filters such as type, status, visibility, owner, tags, and memory_role

Search

• POST /api/search with optional filters including type, tags, visibility, owner, and memory_role
• Search results may include an edges summary with count and relations. The summary does not include neighbor content. Pass expand_graph when the response should include connected entities.

Tasks

• POST /api/tasks
• GET /api/tasks
• PATCH /api/tasks/:id
• POST /api/tasks/:id/complete

Document sync

• POST /api/sync/diff
• POST /api/sync/upload
• POST /api/sync/finalize
• POST /api/sync
• GET /api/sync/status/:repo

Knowledge graph

• POST /api/edges
• DELETE /api/edges/:id
• GET /api/entities/:id/edges
• GET /api/entities/:id/graph

Queue / enrichment

• GET /api/queue (optional ?include_failures=true)

Notes

REST returns full JSON payloads. Token-optimized compact formats are handled in MCP/CLI layers.

Create example:

curl -X POST http://127.0.0.1:3100/api/entities \
  -H "Authorization: Bearer $PGM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"memory","content":"project context","tags":["notes"]}'

List only session-context memories:

curl "http://127.0.0.1:3100/api/entities?type=memory&memory_role=session_context" \
  -H "Authorization: Bearer $PGM_API_KEY"

Search durable memory:

curl -X POST http://127.0.0.1:3100/api/search \
  -H "Authorization: Bearer $PGM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"deployment constraint","type":"memory","memory_role":"durable_memory"}'

Search with graph traversal:

curl -X POST http://127.0.0.1:3100/api/search \
  -H "Authorization: Bearer $PGM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"who owns the rollout blocker","expand_graph":true}'