Plan API

Submit Markdown, let someone adjust the decisions, then retrieve the changes.

Create

POST /api/plans
Content-Type: application/json

{
  "title": "Project map",
  "brief": "Explore project dependencies.",
  "content": "## Validation\n\nRun [essential checks](input:testing) before shipping.",
  "parameters": [
    {
      "id": "testing",
      "label": "Testing effort",
      "type": "slider",
      "value": 1,
      "min": 0,
      "max": 2,
      "summaries": {
        "0": "manual checks",
        "1": "essential checks",
        "2": "integration tests"
      },
      "previews": {
        "0": "Verify the core flow by hand.",
        "1": "Build and core-flow smoke test.",
        "2": "Test persistence and graph interactions."
      }
    }
  ]
}

Returns the record and planUrl. Share that URL for review.

Inline decisions

Place a Markdown link with an input: destination wherever a value belongs: [essential checks](input:testing). Its ID matches a parameter. The current value replaces the link text; optional summaries provide short labels, while previews explain values inside the expanded control. References in paragraphs, headings, lists, quotes, and tables expand below their containing block. Repeated references share one value. Only referenced parameters appear.

Markdown without inputs is a plain reading experience. Fenced Mermaid diagrams render as diagrams. Raw HTML is disabled.

Inputs

Supported types: slider, number, text, textarea, select, toggle, multi-select, radio, choice-cards, list, ranking, range, date, date-range, url, and file.

Every input needs an id, label, type, and value. Select and choice inputs use options. Numeric controls accept min, max, and step. Sliders default to 0–5. A select can use presentation: "radio" or "cards".

[
  {
    "type": "multi-select",
    "value": [
      "A"
    ],
    "options": [
      "A",
      "B"
    ]
  },
  {
    "type": "ranking",
    "value": [
      "B",
      "A"
    ],
    "options": [
      "A",
      "B"
    ]
  },
  {
    "type": "list",
    "value": [
      "First",
      "Second"
    ]
  },
  {
    "type": "range",
    "value": [
      1,
      4
    ]
  },
  {
    "type": "date",
    "value": "2026-10-01"
  },
  {
    "type": "date-range",
    "value": {
      "start": "2026-10-01",
      "end": "2026-10-15"
    }
  },
  {
    "type": "file",
    "value": [
      {
        "name": "note.txt",
        "type": "text/plain",
        "size": 3,
        "data": "YWJj"
      }
    ]
  }
]

Dates may be empty. URLs must use HTTP(S) or be empty. Attachments are base64 with matching byte sizes: 256 KiB per file, 512 KiB total. Uploads remain in the immutable original even if removed from the current plan.

Retrieve

GET /api/plans
GET /api/plans/{id}
GET /api/plans/{id}?full=true

The list returns summaries. An individual plan returns JSON Patch changes against the immutable original; ?full=true returns the complete record. Read status to distinguish draft from ready. Marking ready does not notify an agent.

Update

PATCH /api/plans/{id}
Content-Type: application/json

{ "revision": 1, "plan": { "title": "Project map", "content": "…" }, "status": "draft" }

Send the latest revision and the complete plan, retaining custom metadata. A plan update replaces the plan and defaults to draft. Every save increments revision; a stale revision returns 409. Browser writes must match the configured origin.

Plans have a title, brief, Markdown content, and optional parameters. Extra metadata is preserved. Requests are limited to 1 MB. This public research workspace uses single-process JSON storage.