From 386e5a9748d676a04513a57007b5bd7d21b186d9 Mon Sep 17 00:00:00 2001 From: Jake Fineman Date: Tue, 4 Aug 2026 20:23:01 -0400 Subject: [PATCH 1/3] docs: rewrite README to house standard with grounded claims Expand the README to WAVE's house style (badges, quick start, links row, grounded status/usage sections) while keeping every capability claim traceable to something actually in this repo (source, package.json, capabilities.json, or the published npm/registry artifact). --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 55 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b91ff03..32f9150 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,81 @@ -# WAVE API specification +
-OpenAPI 3.1 specification for the WAVE enterprise streaming platform APIs. +# api-spec -## Overview +**OpenAPI 3.1 specification for the WAVE streaming platform API — 43 documented endpoints across 16 tag groups (streaming, production, analytics, voice, captions, clips, and more), plus generators for client SDKs.** -Complete API specification covering 34 API modules: streaming, production, analytics, voice, captions, chapters, clips, phone, collaboration, search, and more. +![kind](https://img.shields.io/badge/kind-openapi--spec-555?style=flat-square) ![domain](https://img.shields.io/badge/domain-api-0a7?style=flat-square) ![format](https://img.shields.io/badge/format-OpenAPI%203.1-85ea2d?style=flat-square) ![visibility](https://img.shields.io/badge/visibility-public-brightgreen?style=flat-square) ![license](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square) -## Usage +[wave.online](https://wave.online) · [Docs](https://docs.wave.online) · [github](https://github.com/wave-av/api-spec) · [Status](https://wave.online/status) + +
+ +--- + +## What this is + +A single-file OpenAPI 3.1 document (`openapi.yaml`) describing the WAVE Enterprise Streaming Platform +API: 43 endpoint paths grouped under 16 tags. It is the source of truth other WAVE packages generate +from — the [`@wave-av/sdk`](https://www.npmjs.com/package/@wave-av/sdk) TypeScript client is built from +this spec. + +## Quick start ```bash -# Preview with Redoc +# Preview the spec in a browser (Redoc) npx @redocly/cli preview openapi.yaml -# Validate +# Lint / validate npx @redocly/cli lint openapi.yaml -# Generate SDKs +# Generate a client SDK (example: TypeScript fetch client) npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./sdk/typescript ``` ## Authentication -All API requests require a Bearer token: +Every documented endpoint requires a Bearer token: ``` Authorization: Bearer YOUR_API_KEY ``` -Get your API key at [wave.online/developers](https://wave.online/developers). +## Errors + +The spec documents a normalized error envelope used across all endpoints: + +```json +{ "error": { "code": "...", "message": "...", "details": "...", "suggestions": "...", "did_you_mean": "...", "doc_url": "..." } } +``` -## Related +List endpoints support `page` / `perPage` pagination, and requests are subject to rate limiting +(responses include a `Retry-After` header when throttled) — both per the spec's top-level description. -- [@wave-av/sdk](https://www.npmjs.com/package/@wave-av/sdk) — TypeScript SDK (34 API modules) -- [@wave-av/adk](https://www.npmjs.com/package/@wave-av/adk) — Agent Developer Kit -- [@wave-av/mcp-server](https://www.npmjs.com/package/@wave-av/mcp-server) — MCP server for AI tools -- [@wave-av/cli](https://www.npmjs.com/package/@wave-av/cli) — Command-line interface +## Repo layout + +| Path | What it is | +| --- | --- | +| `openapi.yaml` | The spec itself — 3,589 lines, 43 paths, 16 tags | +| `capabilities.json` | Machine-readable lifecycle metadata (this spec is tagged `ga`, version 3.0.0) | +| `scripts/public-repo-guard` | CI check that keeps this public mirror free of internal-only content | + +## Related packages + +| Package | Description | +| --- | --- | +| [@wave-av/sdk](https://www.npmjs.com/package/@wave-av/sdk) | TypeScript SDK generated against this spec | +| [@wave-av/adk](https://www.npmjs.com/package/@wave-av/adk) | Agent Developer Kit | +| [@wave-av/mcp-server](https://www.npmjs.com/package/@wave-av/mcp-server) | MCP server exposing WAVE APIs as tools | +| [@wave-av/cli](https://www.npmjs.com/package/@wave-av/cli) | Command-line interface | ## License Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). + +--- + +
+ +**Built by [WAVE Online, LLC](https://wave.online)** · [wave.online](https://wave.online) · [Docs](https://docs.wave.online) + +
From 2afdfda643b2534b36d6d581f21de6db23b44dc0 Mon Sep 17 00:00:00 2001 From: Jake Fineman Date: Tue, 4 Aug 2026 20:46:15 -0400 Subject: [PATCH 2/3] fix(docs): correct tag count and auth claim in README - README claimed 16 tags; openapi.yaml declares 17 (MoQ and Render were added recently). Fixed in header, "What this is", and repo layout table. - README claimed every endpoint requires a Bearer token; renderVideo, renderPoll, and renderEvents set security:[] and use an x402 payment challenge instead. Qualified the claim. - Added the required CHANGELOG.md Unreleased entry for the README rewrite per AGENTS.md. --- CHANGELOG.md | 7 +++++++ README.md | 10 ++++++---- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 74f79ab..3533da2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -46,3 +46,10 @@ All notable changes to this project are documented here. The format is based on `kind: render` envelopes). - `WaveAttestation` — full v1 wire envelope schema with `id`/`kind`/`v`/`subject`/ `alg`/`sig`/`created` fields and the `alg`/`sig` invariant. + +### Documentation + +- **README rewrite** — refreshed the top-level README to reflect the current spec: corrected + the tag count (16 → 17, now including `MoQ` and `Render`) and clarified that the x402-payable + render operations (`renderVideo`, `renderPoll`, `renderEvents`) are exceptions to the + Bearer-token authentication requirement. diff --git a/README.md b/README.md index 32f9150..5ebe279 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # api-spec -**OpenAPI 3.1 specification for the WAVE streaming platform API — 43 documented endpoints across 16 tag groups (streaming, production, analytics, voice, captions, clips, and more), plus generators for client SDKs.** +**OpenAPI 3.1 specification for the WAVE streaming platform API — 43 documented endpoints across 17 tag groups (streaming, production, analytics, voice, captions, clips, and more), plus generators for client SDKs.** ![kind](https://img.shields.io/badge/kind-openapi--spec-555?style=flat-square) ![domain](https://img.shields.io/badge/domain-api-0a7?style=flat-square) ![format](https://img.shields.io/badge/format-OpenAPI%203.1-85ea2d?style=flat-square) ![visibility](https://img.shields.io/badge/visibility-public-brightgreen?style=flat-square) ![license](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square) @@ -15,7 +15,7 @@ ## What this is A single-file OpenAPI 3.1 document (`openapi.yaml`) describing the WAVE Enterprise Streaming Platform -API: 43 endpoint paths grouped under 16 tags. It is the source of truth other WAVE packages generate +API: 43 endpoint paths grouped under 17 tags. It is the source of truth other WAVE packages generate from — the [`@wave-av/sdk`](https://www.npmjs.com/package/@wave-av/sdk) TypeScript client is built from this spec. @@ -34,7 +34,9 @@ npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-f ## Authentication -Every documented endpoint requires a Bearer token: +Most documented endpoints require a Bearer token (the x402-payable `/render` operations — +`renderVideo`, `renderPoll`, `renderEvents` — are the exception; they set `security: []` and +authenticate via an x402 payment challenge instead): ``` Authorization: Bearer YOUR_API_KEY @@ -55,7 +57,7 @@ List endpoints support `page` / `perPage` pagination, and requests are subject t | Path | What it is | | --- | --- | -| `openapi.yaml` | The spec itself — 3,589 lines, 43 paths, 16 tags | +| `openapi.yaml` | The spec itself — 3,589 lines, 43 paths, 17 tags | | `capabilities.json` | Machine-readable lifecycle metadata (this spec is tagged `ga`, version 3.0.0) | | `scripts/public-repo-guard` | CI check that keeps this public mirror free of internal-only content | From ab89c73d1ec4b66a7cc0e6dfa99f995c47f3e16c Mon Sep 17 00:00:00 2001 From: Jake Fineman Date: Tue, 4 Aug 2026 21:16:44 -0400 Subject: [PATCH 3/3] docs: fix error-envelope example field types in README `details` is typed as an object and `suggestions`/`did_you_mean` as arrays of strings in the Error schema (openapi.yaml), but the README example rendered all three as plain strings, which would lead readers to build the wrong client type. --- CHANGELOG.md | 6 ++++-- README.md | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3533da2..3badfa5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,8 @@ All notable changes to this project are documented here. The format is based on ### Documentation - **README rewrite** — refreshed the top-level README to reflect the current spec: corrected - the tag count (16 → 17, now including `MoQ` and `Render`) and clarified that the x402-payable + the tag count (16 → 17, now including `MoQ` and `Render`), clarified that the x402-payable render operations (`renderVideo`, `renderPoll`, `renderEvents`) are exceptions to the - Bearer-token authentication requirement. + Bearer-token authentication requirement, and fixed the error-envelope example to match the + `Error` schema's actual field types (`details` is an object, `suggestions`/`did_you_mean` are + arrays, not strings). diff --git a/README.md b/README.md index 5ebe279..6f0ab66 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Authorization: Bearer YOUR_API_KEY The spec documents a normalized error envelope used across all endpoints: ```json -{ "error": { "code": "...", "message": "...", "details": "...", "suggestions": "...", "did_you_mean": "...", "doc_url": "..." } } +{ "error": { "code": "...", "message": "...", "details": { "field": "..." }, "suggestions": ["..."], "did_you_mean": ["..."], "doc_url": "..." } } ``` List endpoints support `page` / `perPage` pagination, and requests are subject to rate limiting