API Reference

The xkg-server REST API. Conforms to the Stability Contract and the SLO.

Base URL: https://<your-hub>/api — self-hosted in the default configuration; the same server also serves /frontend/<file> as static assets.

Auth: Bearer token in Authorization. Tokens are issued by the desktop client at first launch and stored in your OS keychain.

Last revised: 2026-08-21

1. Conventions

1.1 Request shape

JSON bodies unless the endpoint says otherwise.
Content-Type: application/json on every POST / PUT / PATCH.
Query string for filters; body for mutations.
Idempotency-Key header is accepted on all mutating endpoints; if absent we generate one client-side.

1.2 Response shape

JSON; Content-Type: application/json; charset=utf-8.
Successful response: { "data": ..., "request_id": "<ulid>" }.
Error response: { "error": "<code>", "message": "...", "request_id": "..." }.

1.3 Common error codes

HTTP	`error`	Meaning
400	`bad_request`	Malformed JSON, missing required field, or invalid enum value.
401	`unauthorized`	Missing / expired bearer token.
403	`forbidden`	Token valid but does not have the requested scope.
404	`not_found`	No resource matches `<resource_id>`.
409	`conflict`	Idempotency-Key reused with a different payload.
422	`unprocessable`	Semantically invalid (e.g. body parses but `client_msg_id` is empty).
429	`rate_limited`	Back off; see `Retry-After` header.
500	`internal`	Server-side bug. The `request_id` is what we need.
503	`unavailable`	Hub is in maintenance or out of disk.

2. Health & metadata

GET /api/health

Liveness + readiness check. Never authenticated; never rate-limited.

curl -s https://<your-hub>/api/health

{
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "api_version": "1.0.0",
    "uptime_seconds": 86123,
    "schema_version": 7,
    "device_count": 3
  },
  "request_id": "01JC..."
}

GET /api/dashboard

The single endpoint that powers the home dashboard. Returns counts and the last 24h activity timeline.

curl -s -H "Authorization: Bearer $TOKEN" \
  https://<your-hub>/api/dashboard

3. Knowledge graph

GET /api/conversations

List captured conversations, newest first. Stable.

Query	Default	Meaning
`limit`	50	1–500.
`offset`	0	Cursor-style pagination; use the previous response's `next_offset`.
`llm`	(none)	One of `chatgpt`, `claude`, `grok`, `gemini`.
`since`	(none)	RFC 3339 timestamp; returns rows with `updated_at > since`.

GET /api/conversations/<conv_id>

One conversation with full message list.

GET /api/conversations/index

The keyword index used by the FTS5-backed search box. Returns { keyword: hit_count } for the top 100 terms in your store.

GET /api/topics

Trending topics across all LLMs in the last 30 days. Sorted by mention count desc.

GET /api/ai-topics

Same as /api/topics but restricted to ChatGPT / Claude / Gemini (via the LLM extractors).

GET /api/grok-topics

Same, restricted to Grok-sourced conversations.

4. Actions & todos

GET /api/actions

Action items extracted from your conversations.

Query	Default	Meaning
`limit`	100	1–1,000.
`priority`	(none)	`p0` / `p1` / `p2` / `p3`.
`status`	open	`open` / `done` / `archived`.
`since`	(none)	RFC 3339 timestamp.

5. Tweets & posts

GET /api/tweets

Bookmarked tweets you've imported. Sorted by created_at desc.

GET /api/tweet-conversations

Conversations that started as a bookmarked tweet (used for the "tweet → thread" linking feature).

GET /api/tweets/<tweet_id>/related

Tweets related to the given one by FTS5-similarity threshold 0.8.

GET /api/posts

Same shape as /api/tweets but for long-form posts.

GET /api/public-graphs

The list of graphs you've marked public. Stable.

6. Tabs (browser)

GET /api/tabs/recent

Last 100 captured tabs across all open windows.

POST /api/tabs/import

Bulk import a browser tab dump (Chrome / Brave export format). Body is the JSON form produced by the TabMind extension.

POST /api/tab-import

Single-tab import (legacy endpoint, kept for back-compat; prefer /api/tabs/import for new clients).

7. Graph visualization

GET /api/graph/d3

D3-friendly graph dump: { nodes: [...], edges: [...] }. Used by the dashboard's force-directed view. Supports ?root=<node_id> to restrict to a 2-hop neighborhood.

8. Sync

See the dedicated Sync architecture doc for threat model + envelope shape. The relevant endpoints:

Method	Path	Stability
POST	`/api/sync/devices`	Stable
POST	`/api/sync/upload`	Stable
GET	`/api/sync/download`	Stable
GET	`/api/sync/download?since={cursor}`	Beta

9. Operations

POST /api/reload

Hot-reload the in-memory data caches without restarting the process. Authenticated; admin scope required.

GET /

Returns the static SPA index. Not part of the JSON API; do not script against it.

GET /frontend/<path:filename>

Static files served from the bundled frontend/ directory.

10. Versioning & deprecation

Every endpoint is tagged with one of three stability tiers in the table above. The full contract — deprecation window, removal policy, breaking-change process — lives in the API Stability Contract.