ZCKR.DEV DEVELOPER RESOURCES

ZCKR.DEV REST API

A read-only JSON API over the same content the pages render. Every success is a { data, meta } envelope; every failure is a problem document. No authentication.

• GET /api/v1Index of every endpoint, the rate limit, the version lifecycle
• GET /api/v1/projectsProjects; filter with status and type
• GET /api/v1/projects/{slug}One project in full, cause of death included
• GET /api/v1/notesNotes and TILs; filter with kind
• GET /api/v1/notes/{slug}One note with its markdown body
• GET /api/v1/agentsThe agent registry; filter with status
• GET /api/v1/agents/{slug}One agent, including where it fails
• GET /api/v1/mcpMCP servers; filter with status and origin
• GET /api/v1/mcp/{slug}One MCP server and its tool catalogue
• GET /api/v1/systemsThe infrastructure inventory
• GET /api/v1/graph?node=The whole entity graph, or one node's neighbours
• GET /api/v1/stackThe instrument list
• GET /api/v1/currentsLatest monthly snapshot
• GET /api/v1/currents/{month}An archived snapshot, YYYY-MM
• GET /api/v1/ideasThe unbuilt ideas backlog
• GET /api/v1/search?q=Full-text search across the lab
• GET /api/v1/versionThe versioning and deprecation policy

curl -s https://zckr.dev/api/v1/projects?status=dead

Read-only in the strict sense: any write verb answers 405 with an Allow header.

ERRORS

Every failure is RFC 9457 problem details, served as application/problem+json — never an HTML error page, including for an unknown path under /api. Two members beyond the RFC: code, a stable machine-readable string to branch on, and resolution, a concrete next step.

{
  "type": "https://zckr.dev/developers#error-not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No project with slug \"nope\".",
  "instance": "/api/v1/projects/nope",
  "code": "not_found",
  "resolution": "Valid slugs: zckr-dev, llm-wiki, … The full list is at /api/v1/projects.",
  "documentation": "https://zckr.dev/developers#errors"
}

THE CATALOGUE

• invalid_parameter400A query or path parameter was missing or outside its allowed values. The resolution names what would have been accepted.
• not_found404No such resource. The resolution lists every valid slug or month, so a second guess is unnecessary.
• method_not_allowed405This API is read-only. Any write verb answers this, with an Allow header naming GET, HEAD and OPTIONS.
• not_acceptable406The Accept header excludes application/json. The problem document is returned anyway, as RFC 9457 intends.
• rate_limited429The published window is exhausted. Retry-After says how long to wait; the RateLimit header reports the live window.
• internal_error500An unexpected failure. Retry once, then report it via the contact page with the instance value.

RATE LIMITS

120 requests per 60 seconds per client. Every response carries the IETF RateLimit and RateLimit-Policy structured fields, plus the legacy RateLimit-Limit/-Remaining/-Reset trio. A 429 adds Retry-After.

Honest accounting: the window lives in the memory of whichever instance answers, so the effective ceiling across a warm fleet is higher than the published number, never lower. An agent that throttles to these headers will not be limited.

VERSIONING AND DEPRECATION

The major version is in the URL path and echoed in the API-Version response header. A breaking change — removing or renaming a field, narrowing a type, removing an endpoint — ships as a new path, never as a change to an existing one. Additive changes happen in place, so parse leniently and ignore keys you do not know.

A deprecated version answers every request with an RFC 9745 Deprecation header and an RFC 8594 Sunset header. No version is switched off less than 180 days after its Deprecation header first appears.

ZCKR.DEV MCP SERVER

A read-only MCP server exposing the lab's content as tools over the Streamable HTTP transport. No authentication.

Eight tools, all read-only: lab_list_projects, lab_get_project, lab_list_notes, lab_get_note, lab_list_agents, lab_get_agent, lab_list_mcp_servers, lab_list_systems, lab_get_graph, lab_get_stack, lab_get_currents, lab_list_ideas, lab_search.

curl -s https://zckr.dev/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The reply is application/json unless the client actually prefers text/event-stream — by naming it alone, or ranking it above JSON with a q-value. The transport permits either representation for a single request/response.

ZCKR.DEV A2A AGENT

The same lab as an Agent2Agent peer, for a caller that would rather ask a question than choose a tool. Read-only, unauthenticated, and answered synchronously — a task is complete before the response is written.

Four skills, each with the phrasings that reach it in the card: search_lab, get_project, list_projects, current_focus.

curl -s https://zckr.dev/api/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"role":"user","kind":"message","messageId":"1","parts":[{"kind":"text","text":"What killed Nexus?"}]}}}'

A2A has two live wire shapes. This agent implements 0.3, says so in the card, and answers -32009 VersionNotSupported to an A2A-Version header asking for another — rather than accepting the header and serving a shape it did not promise. It is stateless, so tasks/get answers -32001 for every id and says why.

ZCKR.DEV SOAP SERVICE

A WSDL 1.1 contract over the same records, for a toolchain that generates its client from a document rather than from prose. Both a SOAP 1.1 and a SOAP 1.2 binding, document/literal, no WS-Security, no sessions.

wsimport -keep https://zckr.dev/api/soap?wsdl

curl -s -X POST https://zckr.dev/api/soap \
  -H 'content-type: text/xml; charset=utf-8' \
  -H 'SOAPAction: "https://zckr.dev/soap/lab/v1/ListProjects"' \
  -d '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="https://zckr.dev/soap/lab/v1"><soap:Body><tns:ListProjects><tns:status>dead</tns:status></tns:ListProjects></soap:Body></soap:Envelope>'

Faults carry the same code and resolution members the REST problem documents do — an unknown slug lists every valid one, whichever envelope you asked in. The two versions genuinely differ: 1.1 uses faultcode/faultstring and HTTP 500, 1.2 uses Code/Value and HTTP 400 for a sender fault. Both are served correctly rather than one being served to everybody.

ZCKR CLI

A dependency-free Node client for the REST API above, for scripting without writing an integration first.

git clone the repo, then node packages/cli/bin/zckr.mjs
node packages/cli/bin/zckr.mjs projects --status=dead

Not on npm yet. The CLI is written, tested and in the repository; it has not been published to the registry, so npm install -g @zckr/cli would fail today and is deliberately not printed above. Until it lands, the REST API is the surface to integrate against — the CLI is a client of it and can do nothing the API cannot.

Commands mirror the endpoints: projects, project <slug>, notes, note <slug>, agents, agent <slug>, mcp, server <slug>, systems, graph, stack, currents, ideas, search <query>, api, version. --json prints the raw envelope for piping into jq.

MARKDOWN MIRRORS

Every page is also a markdown document. Ask for it by content negotiation on the canonical URL, or append .md to the path. Unknown paths answer with a markdown 404 that carries recovery links.

curl -H 'Accept: text/markdown' https://zckr.dev/stack
curl https://zckr.dev/stack.md

Negotiated responses carry Vary: Accept, and HTML responses advertise their twin with an RFC 8288 Link header.

OPENAPI DESCRIPTION

An OpenAPI 3.1 document covering exactly the surface on this page — nothing aspirational. Every operation has a unique operationId, a description, and a typed response schema; every 4xx and 5xx references the same problem schema.

INDEXES AND FEEDS

Start at llms.txt: it explains when this site is worth reading and links every project and note by URL.

USAGE AND HONESTY

• –No authentication, no accounts, no forms, no tracking — see the privacy page for the full accounting.
• –Everything is statically generated: URLs are stable and safe to cache.
• –Content marked sample: true is placeholder seed data. Do not cite it as fact.
• –Cite pages by their canonical URL. Corrections are welcome via the contact page.