surfaceREST JSON over HTTPS

authClerk session JWT (bearer)

covered todayNotes, sources, recall

stanceScaffold in active use

Use this when: you want Readwise, NotebookLM exports, Obsidian scripts, or internal tools to land structured text and highlights in Consilium without pasting through the UI alone. You are comfortable issuing HTTP calls with a user-scoped token and JSON bodies.

authentication

One header, every request.

Send Authorization: Bearer <clerk_session_jwt>. Obtain a session by signing into the Consilium app. Local development may allow a fixed bearer matching a dev user id when explicitly enabled in the API environment.

notes

Create, read, update, delete, and list.

Endpoints follow POST /api/notes, GET /api/notes/{note_id}, PATCH /api/notes/{note_id}, and DELETE /api/notes/{note_id}. Optional fields include domain and view slugs. GET /api/library/writing returns a summary list of notes on your writing shelf.

example

Create a note

curl -sS -X POST "$CONSILIUM_API/api/notes" \
  -H "Authorization: Bearer $CONSILIUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q3 board risk memo",
    "body_md": "We should tighten vendor oversight before the audit.",
    "domain_slug": "risk-management",
    "view_slug": "vendor-oversight"
  }'

sources

Readwise import.

Bulk-import highlights with POST /api/sources/readwise/import. Sources deduplicate on title and URL. New sources are created when needed; highlights attach to the matching source. Single-highlight follow-up on an existing source uses POST /api/sources/{source_id}/highlights.

example

Import highlights

curl -sS -X POST "$CONSILIUM_API/api/sources/readwise/import" \
  -H "Authorization: Bearer $CONSILIUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_slug": "risk-management",
    "highlights": [
      {
        "source_title": "Vendor risk in regulated sectors",
        "text": "Third-party concentration is the fastest path to an audit finding.",
        "url": "https://example.com/article",
        "kind": "article"
      }
    ]
  }'

recall

Spaced cards from claims.

Recall cards are generated from claim blocks on notes. The API refreshes from notes before listing due items. List due cards with GET /api/recall/due?limit=20. Submit outcomes with POST /api/recall/{card_id}/rate using integer ratings 1 to 4 (again, hard, good, easy).

webhooks and subscriptions

Roadmap, not current surface.

Inbound automation from external SaaS (for example Readwise export webhooks into Consilium), richer notebook export contracts, and full Obsidian round-trip sync are planned for a later cycle. Bidirectional sync and webhook subscriptions are not part of the scaffold described here. If you need that behaviour on a fixed date, say so when you brief us.

errors

What usually breaks.

401 missing or invalid bearer token.
404 note, card, prediction, source, or synthesis id not found.
400 malformed body or missing id. Responses are JSON with a detail string.

Wire your stack into Consilium. Same writing lane, machine-readable.