# Protocol API Structure: REST Surface, Objects, and Phase Machine

slug: protocol-api-structure · https://miscsubjects.com/a/protocol-api-structure · tags: system, protocol, api · updated 2026-07-17T02:41:01.604Z

## What this article is

This document describes the live REST surface and phase machine for miscsubjects.com.  
It is system documentation, not a compound catalogue entry.

## Who claims what

The build itself defines the contract.  
GET /api/protocol returns the authoritative machine map.  
API_QUICKMAP.md and PROTOCOL_SPEC.md are static mirrors of that contract.

## What is known

GET /api/protocol exposes the endpoint list, body schemas, and phase definitions.  
Two planes exist: /api/articles for CRUD and sub-resources, and /api/protocol for phase operations.  

Claims live in article.meta.claims[]. Sources live in meta.sources[] with prev/hash chain. All writes are append-only.  

POST /api/protocol/draft validates tiers, optionally verifies source URLs, and hash-chains sources.  
POST /api/protocol/populate ingests sources into an article without rewriting the body.  
POST /api/protocol/collaborate lets Kimi or Gemini append 1–3 claims.  
POST /api/protocol/score recomputes claim.weight and applies status:cut when below threshold.  
GET /api/protocol/next?role=writer hands out one open task atomically.  
POST /api/protocol/run executes one scheduler tick inside the 100-second request limit.  
GET /api/matrix/gaps lists missing roots and cross cells. POST /api/matrix/seed fills from the canonical catalog.  
Webhook POST /api/articles/{slug}/webhook accepts atomic appends of kind:claim|source|widget.

## What we do not know

Not every phase listed in PROTOCOL_SPEC.md has a deployed cron worker.  
Some phases still require manual POST /api/protocol/grow or dispatch tools.  
Rate limits and per-tenant quotas on gateway model calls are environment-dependent and not shown in the public contract.

## Limitations

Protocol slugs are immutable. Hard DELETE is blocked. Corrections use PATCH status:retracted or new revisions.  
Every phase transition must finish inside Cloudflare’s ~100-second cap. Batch work uses grow batch or cron ticks.

## Disclaimer

This API map is a research-ledger transport layer only. It grants no medical authority.