PROJECTSKILLSCONNECTING…

SYS.52 / API

The HTTP API

REST, JSON, under /api. What its conventions guarantee, and where the exhaustive route list is not.

Surfaces3 SECTIONS

The shape

Everything validated at the boundary; nothing unvalidated reaches a service.

ERROR BODY
{ "error": { "code": "SNAKE_CASE", "message": "…", "details": { } } }
  • Anything that enqueues work answers 202 with a job id rather than blocking. Analysis, regeneration and review are all queued.
  • Hitting a plan limit is a 422 whose message names the limit and when it resets — never a bare "limit reached".
  • Mutating routes are rate limited.
  • A project-scoped route resolves membership before the handler runs.

A non-member gets 404, never 403

Because 403 would confirm the id exists.

This is why a project id is safe to put in a committed file, and why the id in a URL is not something to protect. The same reasoning governs share links: a revoked link, an expired link and a link that never existed all answer identically.

What is addressable

The families, rather than the list.

Projects and sources
Creating a project, attaching a source, starting an ingestion.
Analysis
Starting a run, and following its steps while it executes.
Snapshot-scoped reads
Intelligence, Constitution, Skills, graph, findings, constraints and the change set, each addressed by the snapshot it belongs to.
Skills
Reading, regenerating, requesting and removing.
KEEL
Sessions, turns, and the artefacts a session produces.
Usage
What has been spent, by day, project, task and model.
DOCS23 CHAPTERS