From b3354e25106fac180c7369514ee4748ee481589a Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Tue, 21 Jul 2026 18:41:08 -0500 Subject: [PATCH] docs: document real filter behavior on API request pages Ground the query/filter parameter docs in the daemon source (coven-cli api.rs + store.rs) instead of partial descriptions: - Hoist the events cursor filters (afterSeq, afterEventId, limit) into shared components/parameters so GET /events and the path-scoped variant cannot drift, and document previously omitted behavior: afterSeq wins when both cursors are supplied, non-integer values fail with 400 invalid_request, unknown afterEventIds read from the start of the log, out-of-range limits clamp to 1-1000, and hasMore is only meaningful when a limit is set - Fix the misleading GET /sessions description: the endpoint accepts no filter parameters and there is no archived query flag; archived records are CLI/TUI-only (coven sessions --all) - Hide the stray pill rendered before API routes: fumadocs-openapi emits the leading empty path segment as an empty , which the dark-mode inline-code styling turned into a blob Co-Authored-By: Claude Fable 5 --- app/globals.css | 8 +++ openapi/coven.daemon.v1.yaml | 101 ++++++++++++++++++----------------- 2 files changed, 59 insertions(+), 50 deletions(-) diff --git a/app/globals.css b/app/globals.css index 65a891a..ec51758 100644 --- a/app/globals.css +++ b/app/globals.css @@ -221,6 +221,14 @@ a:hover { color: var(--coven-violet-light); } font-size: 0.875em; } +/* fumadocs-openapi splits API routes on "/" and renders the leading empty + * segment as an empty ; the pill styling above turns it into a stray + * blob before the path (e.g. "GET ▢/sessions"). An empty inline code never + * carries content, so hide it everywhere. */ +:not(pre) > code:empty { + display: none; +} + @media print { #nd-docs-layout { --fd-sidebar-width: 0px !important; diff --git a/openapi/coven.daemon.v1.yaml b/openapi/coven.daemon.v1.yaml index 4473dc2..7ed0db6 100644 --- a/openapi/coven.daemon.v1.yaml +++ b/openapi/coven.daemon.v1.yaml @@ -185,9 +185,10 @@ paths: description: | Returns all active, non-archived sessions known to this daemon. - Archived sessions are excluded; surface them through the CLI via - `coven sessions --all` or via tooling that calls this endpoint twice - (with and without archived filtering). + This endpoint accepts no filter parameters: archived sessions are + always excluded, and there is no `archived` query flag. Archived + records are surfaced through the CLI (`coven sessions --all`) and + TUI, which read the session store directly. responses: '200': description: List of active sessions. @@ -587,33 +588,13 @@ paths: - name: sessionId in: query required: true - description: Session id whose events should be returned. + description: Session id whose events should be returned. Requests without it fail with `400 invalid_request`. schema: type: string examples: [session-1] - - name: afterSeq - in: query - required: false - description: Preferred cursor. Returns events with `seq > afterSeq`. - schema: - type: integer - minimum: 0 - examples: [41] - - name: afterEventId - in: query - required: false - description: Compatibility cursor, resolved by the daemon to a sequence position. - schema: - type: string - examples: [event-41] - - name: limit - in: query - required: false - description: Maximum number of events to return, clamped to 1–1000. When omitted, all events after the cursor are returned. - schema: - type: integer - minimum: 1 - maximum: 1000 + - $ref: '#/components/parameters/AfterSeq' + - $ref: '#/components/parameters/AfterEventId' + - $ref: '#/components/parameters/EventsLimit' responses: '200': description: A page of events. @@ -640,29 +621,9 @@ paths: cursor parameters and response shape, with the session id taken from the path instead of a `sessionId` query parameter. parameters: - - name: afterSeq - in: query - required: false - description: Preferred cursor. Returns events with `seq > afterSeq`. - schema: - type: integer - minimum: 0 - examples: [41] - - name: afterEventId - in: query - required: false - description: Compatibility cursor, resolved by the daemon to a sequence position. - schema: - type: string - examples: [event-41] - - name: limit - in: query - required: false - description: Maximum number of events to return, clamped to 1–1000. When omitted, all events after the cursor are returned. - schema: - type: integer - minimum: 1 - maximum: 1000 + - $ref: '#/components/parameters/AfterSeq' + - $ref: '#/components/parameters/AfterEventId' + - $ref: '#/components/parameters/EventsLimit' responses: '200': description: A page of events. @@ -687,6 +648,46 @@ components: schema: type: string examples: [session-1] + AfterSeq: + name: afterSeq + in: query + required: false + description: | + Preferred cursor. Returns events with `seq > afterSeq`; pass + `nextCursor.afterSeq` from the previous page to resume reading. + Takes precedence over `afterEventId` when both are supplied. + Non-integer values fail with `400 invalid_request`. + schema: + type: integer + minimum: 0 + examples: [41] + AfterEventId: + name: afterEventId + in: query + required: false + description: | + Compatibility cursor for clients that stored event ids instead of + sequence numbers. The daemon resolves the id to its sequence position + and returns events after it. Ignored when `afterSeq` is also + supplied; unknown ids read from the start of the log. + schema: + type: string + examples: [event-41] + EventsLimit: + name: limit + in: query + required: false + description: | + Maximum number of events to return. Out-of-range values are clamped + to 1–1000 rather than rejected; non-integer values fail with + `400 invalid_request`. When omitted, all events after the cursor are + returned in one page. `hasMore` in the response is only meaningful + when a limit is set — it is `true` when the page filled the limit. + schema: + type: integer + minimum: 1 + maximum: 1000 + examples: [200] responses: InvalidRequest: