docs(api): wish create and patch endpoints, and the Kafka create command #5

Merged

peterswimm merged 1 commit from feat/wish-write-endpoints into main

2026-09-14 14:34:36 +00:00

peterswimm commented

2026-09-14 02:06:00 +00:00

Owner

Scope

This PR documents the wish write endpoints that ritual-server serves once ritual-engine #620 lands, plus the Kafka command for creating a wish.

POST /api/v1/wishes — create a wish.

Auth: a token is required.
Who files the wish:
- The caller files as itself.
- Naming another actor makes a delegated write. That needs an active frames:write grant from that actor to the caller.
- A static service token has no identity of its own, so it names the actor.
Idempotency: an optional frame_id works as an idempotency key. A retry with the same ID returns 200 and files nothing new.
Responses: 201, 200, 202, 401, 403 and 422.

PATCH /api/v1/wishes/{wish_id} — change a wish.

Attribution: the change is attributed to the caller.
Fields: description, next_step, epic, other context keys, title, priority, progress_pct, status and due_at.
Responses: 200, 401, 403, 404, 409 and 422.

Schemas

Endpoint schemas: WishCreateRequest, WishCreateResponse, WishPatchRequest, WishPatchResponse, and WishWriteError, the error body.
Kafka command: WishCreateCommand, the create command on forge.lineage.wish_created. It is also referenced from the POST operation through an x-kafka-create-command extension.

Version: info.version goes from 0.59.0 to 0.60.0.

Testing

The YAML parses, and info.version reads 0.60.0.
A script confirmed that every #/components/schemas/… and #/components/responses/… reference resolves.
No full OpenAPI validation ran: openapi-spec-validator isn't installed locally, and this repo has no CI to run one.

Impact Statement

Documentation only. No code or runtime behavior changes.
Error schema. The new paths use WishWriteError, which matches the {"error": ...} body ritual-server actually returns. The older shared Error schema, which uses detail, is unchanged.

## Scope This PR documents the wish write endpoints that ritual-server serves once ritual-engine #620 lands, plus the Kafka command for creating a wish. **`POST /api/v1/wishes`** — create a wish. - **Auth:** a token is required. - **Who files the wish:** - The caller files as itself. - Naming another actor makes a delegated write. That needs an active `frames:write` grant from that actor to the caller. - A static service token has no identity of its own, so it names the actor. - **Idempotency:** an optional `frame_id` works as an idempotency key. A retry with the same ID returns 200 and files nothing new. - **Responses:** 201, 200, 202, 401, 403 and 422. **`PATCH /api/v1/wishes/{wish_id}`** — change a wish. - **Attribution:** the change is attributed to the caller. - **Fields:** `description`, `next_step`, `epic`, other `context` keys, `title`, `priority`, `progress_pct`, `status` and `due_at`. - **Responses:** 200, 401, 403, 404, 409 and 422. **Schemas** - **Endpoint schemas:** `WishCreateRequest`, `WishCreateResponse`, `WishPatchRequest`, `WishPatchResponse`, and `WishWriteError`, the error body. - **Kafka command:** `WishCreateCommand`, the create command on `forge.lineage.wish_created`. It is also referenced from the POST operation through an `x-kafka-create-command` extension. **Version:** `info.version` goes from 0.59.0 to 0.60.0. ## Testing - The YAML parses, and `info.version` reads 0.60.0. - A script confirmed that every `#/components/schemas/…` and `#/components/responses/…` reference resolves. - No full OpenAPI validation ran: `openapi-spec-validator` isn't installed locally, and this repo has no CI to run one. ## Impact Statement - **Documentation only.** No code or runtime behavior changes. - **Error schema.** The new paths use `WishWriteError`, which matches the `{"error": ...}` body ritual-server actually returns. The older shared `Error` schema, which uses `detail`, is unchanged.

peterswimm added 1 commit

2026-09-14 02:06:00 +00:00

docs(api): wish create and patch endpoints, and the Kafka create command

PR policy check / policy-gate (pull_request) Successful in 0s

Details

a16580d939

Adds POST /api/v1/wishes and PATCH /api/v1/wishes/{wish_id} as ritual-server
serves them after ritual-engine #620: auth required, the caller files as
itself, delegated writes need a frames:write grant, and errors are mapped from
the database's SQLSTATE. Documents the forge.lineage.wish_created create
command as an x-kafka-create-command extension and a WishCreateCommand schema.
Version 0.59.0 -> 0.60.0.

peterswimm merged commit 3066b5d1b2 into main

2026-09-14 14:34:36 +00:00

peterswimm deleted branch feat/wish-write-endpoints

2026-09-14 14:34:37 +00:00

peterswimm referenced this pull request from a commit

2026-09-14 14:34:37 +00:00

Merge pull request 'docs(api): wish create and patch endpoints, and the Kafka create command' (#5) from feat/wish-write-endpoints into main