KDS Public API (v1) — contract for kds.koder.dev/api/v1/

draft

KDS Public API (v1)

Normative contract for the JSON + text endpoints under https://kds.koder.dev/api/v1/ and the AI-agent discovery surfaces at https://kds.koder.dev/llms.txt + /llms-full.txt.

Consumers today:

  • engines/sdk/koder-design-lsp (editor hover + autocomplete from

    tokens.json, 24h TTL cache)

  • Figma sync (per-deploy snapshot of tokens.json)
  • AI agents (Claude Code, Cursor, Copilot, Gemini) via llms.txt +

    llms-full.txt

  • Internal monitors / scripts
  • Future: MCP server (tools/design-gen#117)

This spec exists so consumers can pin against a known contract and the generator can change implementation without silently breaking them.

Status: *0.1.0 Draft* Move to *atified*when: (a) every endpoint below has a passing contract test in tools/design-gen/tests/regression/, AND (b) at least one external consumer (LSP) is wired to validate against the JSON schemas before parsing.

R1 — Endpoint inventory

The canonical surface, as of v0.1.0:

Path Method Content-Type Purpose
/api/v1/index.json GET application/json Endpoint catalog discovery (10+ endpoints)
/api/v1/specs.json GET application/json Catalog of every published spec (slug + locale URLs + kind + summary)
/api/v1/specs/<slug>.json GET application/json Perspec payload (full frontmatter + body markdown + crossrefs)
/api/v1/specs/openapi.yaml GET text/yaml OpenAPI 3.1 description of `apiv1/specs

Source: ../home/koder/dev/koder/meta/docs/stack/specs/api/kds-public-api.kmd