# info.description
Read-only API for consuming Your Podcast episodes. All endpoints are public, unauthenticated, and safe to call from assistant agents on behalf of a listener. For native MCP clients see POST https://coil-demo.pages.dev/mcp. For natural-language search see POST https://coil-demo.pages.dev/ask (NLWeb-style, JSON or SSE). Versioning: the URL path is intentionally stable and unversioned; clients pin behaviour with the optional API-Version request header (current: 2026-05-18). See x-api-versioning and x-deprecation-policy below.

# info.x-api-versioning.note
The URL path is intentionally unversioned. A breaking change would ship under a new API-Version date; the previous version then enters the deprecation window.

# info.x-deprecation-policy.note
Breaking changes ship under a new API-Version date. The prior version stays supported for at least 180 days, during which its responses carry RFC 8594 Deprecation and Sunset headers and a Link header advertising the successor.

# info.x-error-recovery.retry_guidance.402.note
Payment-required surface at /donate (voluntary tip-jar); the read API is free.

# info.x-error-recovery.retry_guidance.404.note
No such episode or endpoint. Check /sitemap.xml or /episodes.json.

# info.x-error-recovery.retry_guidance.405.note
Wrong HTTP method. See the operation's allowed methods.

# info.x-error-recovery.retry_guidance.429.note
Rate-limited. Honor Retry-After (seconds) before retrying; use exponential backoff for repeated 429s.

# info.x-error-recovery.retry_guidance.500.note
Server-side failure. Retry once with exponential backoff.

# info.x-batch.note
Two batch conventions are defined. (1) The /mcp endpoint accepts a JSON-RPC 2.0 batch — POST an array of request objects (max 50). See JsonRpcBatchRequest / JsonRpcBatchResponse. (2) REST endpoints are single-resource today; future bulk endpoints will use the BatchRequest / BatchResponse envelope (items array in, results array out, each item succeeds or fails independently).

# info.x-webhooks.delivery.signature
hex HMAC-SHA256 of the raw body keyed by the registration secret

# tags[].description
Full-text and natural-language search over episodes.

# tags[].description
Agent-discovery surfaces (status, briefing, RSS, catalog).

# tags[].description
Model Context Protocol server and discovery.

# tags[].description
Event subscriptions (webhook callbacks + WebSub).

# paths./api/search.get.description
Free-text search over episode title, description, and transcript. Returns ranked results with snippets.

# paths./api/search.get.parameters[].description
Number of results to skip (pagination cursor).

# paths./api/search.get.parameters[].description
Opt into the 202 Accepted async pattern. With this set (or `Prefer: respond-async` on the request), the endpoint returns 202 + `Location: /jobs/<id>` + `Retry-After: 1` instead of executing synchronously.

# paths./api/search.get.responses.200.description
Ranked search results with pagination metadata.

# paths./api/search.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./api/search.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./api/search.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./api/search.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./api/search.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./api/search.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./api/search.get.responses.200.headers.Idempotency-Key.description
Echo of the Idempotency-Key request header when present.

# paths./api/search.get.responses.202.description
Accepted — returned when `?async=1` or `Prefer: respond-async` is set. Poll `GET /jobs/{id}` until status is completed.

# paths./api/search.get.responses.202.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./api/search.get.responses.202.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./api/search.get.responses.202.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./api/search.get.responses.202.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./api/search.get.responses.202.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./api/search.get.responses.202.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./ask.post.description
NLWeb-style natural-language ask endpoint. Returns episodes ranked by transcript relevance. Set `Accept: text/event-stream` (or `Prefer: streaming=true`) for SSE streaming with `start`, `result`, `complete` events.

# paths./ask.post.responses.200.description
Either JSON or SSE depending on Accept/Prefer headers.

# paths./ask.post.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./ask.post.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./ask.post.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./ask.post.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./ask.post.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./ask.post.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./ask.post.responses.200.headers.Idempotency-Key.description
Echo of the Idempotency-Key request header when present.

# paths./ask.post.responses.200.content.text/event-stream.schema.description
NLWeb event stream (start, result*, complete).

# paths./ask.post.responses.202.description
Accepted — returned when `?async=1` or `Prefer: respond-async` is set. Body carries the job_id; poll `GET /jobs/{id}` until status flips to completed.

# paths./ask.post.responses.202.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./ask.post.responses.202.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./ask.post.responses.202.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./ask.post.responses.202.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./ask.post.responses.202.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./ask.post.responses.202.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./ask.post.responses.202.headers.Idempotency-Key.description
Echo of the Idempotency-Key request header when present.

# paths./ask.get.summary
Ask the show a question (query-string variant)

# paths./ask.get.description
Same as POST /ask but accepts `?q=` for cheap probing.

# paths./ask.get.responses.200.description
JSON response (use POST + Accept header for SSE).

# paths./ask.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./ask.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./ask.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./ask.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./ask.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./ask.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./jobs.get.description
GET returns a discovery envelope describing the 202 Accepted async pattern: supported kinds, polling URL template, and an example request/response pair.

# paths./jobs.get.responses.200.description
Discovery envelope describing the async surface.

# paths./jobs.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./jobs.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./jobs.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./jobs.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./jobs.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./jobs.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./jobs.post.description
Creates a long-running operation and returns 202 Accepted with `Location: /jobs/<id>` and `Retry-After`. Poll the polling URL until status flips from `pending` to `completed`. The job id encodes the spec, so polling is stateless and resumable. Sending an `Idempotency-Key` folds the key into the id derivation so retries with the same key + body return the same job_id.

# paths./jobs.post.responses.202.description
Accepted — job created. Poll the Location URL.

# paths./jobs.post.responses.202.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./jobs.post.responses.202.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./jobs.post.responses.202.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./jobs.post.responses.202.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./jobs.post.responses.202.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./jobs.post.responses.202.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./jobs.post.responses.202.headers.Idempotency-Key.description
Echo of the Idempotency-Key request header when present.

# paths./jobs/batch.post.summary
Create multiple async jobs in one round-trip (array body)

# paths./jobs/batch.post.description
Bulk version of POST /jobs. Body is a JSON array (max 50) of job specs; the response is a same-length array of 202-style entries, each with its own job_id + poll_url. Per-item or request-wide Idempotency-Key is folded into each job spec for stable retries.

# paths./jobs/batch.post.responses.202.description
Batch accepted. Each result entry mirrors the single-POST 202 envelope.

# paths./jobs/batch.post.responses.202.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./jobs/batch.post.responses.202.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./jobs/batch.post.responses.202.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./jobs/batch.post.responses.202.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./jobs/batch.post.responses.202.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./jobs/batch.post.responses.202.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./jobs/batch.get.description
GET returns a discovery envelope describing the array-body batch surface.

# paths./jobs/batch.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./jobs/batch.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./jobs/batch.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./jobs/batch.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./jobs/batch.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./jobs/batch.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./jobs/{id}.get.description
Returns the current status of a previously-created job. Returns `status: pending` with `Retry-After: 1` for the first second after creation (so probes see a realistic polling round-trip), then `status: completed` with the result populated under `.result`. Stateless — the id encodes the spec.

# paths./jobs/{id}.get.parameters[].description
Skip the pending-window simulation and return the completed result immediately.

# paths./jobs/{id}.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./jobs/{id}.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./jobs/{id}.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./jobs/{id}.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./jobs/{id}.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./jobs/{id}.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./status.get.description
Always 200 when reachable. Use for agent circuit-breaker logic.

# paths./status.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./status.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./status.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./status.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./status.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./status.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./webhooks.get.description
Returns the supported event types, payload schema, delivery semantics, and how to register (JSON callback or WebSub).

# paths./webhooks.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./webhooks.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./webhooks.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./webhooks.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./webhooks.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./webhooks.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./webhooks.post.description
Register a callback URL to receive episode events. Send JSON `{ url, events?, secret? }` for a webhook, or a WebSub form (`hub.mode=subscribe&hub.topic=…&hub.callback=…`). Returns 201 (webhook) or 202 (WebSub) with a `Location` header.

# paths./webhooks.post.requestBody.content.application/json.schema.properties.secret.description
Shared secret for HMAC-SHA256 delivery signatures.

# paths./webhooks.post.responses.201.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./webhooks.post.responses.201.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./webhooks.post.responses.201.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./webhooks.post.responses.201.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./webhooks.post.responses.201.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./webhooks.post.responses.201.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./webhooks.post.responses.202.description
WebSub subscription accepted (intent verification follows out of band).

# paths./webhooks/{id}.parameters[].description
Opaque subscription id from registration.

# paths./webhooks/{id}.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./webhooks/{id}.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./webhooks/{id}.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./webhooks/{id}.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./webhooks/{id}.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./webhooks/{id}.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./webhooks/{id}.delete.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./webhooks/{id}.delete.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./webhooks/{id}.delete.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./webhooks/{id}.delete.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./webhooks/{id}.delete.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./webhooks/{id}.delete.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./donate.post.description
Voluntary tip endpoint. Always returns HTTP 402 with x402 + MPP payment-discovery headers. The free read API never returns 402; only this endpoint does. Payment-aware agents (Coinbase x402, MPP-enabled clients) can route a USDC tip on Base Sepolia testnet by default (configurable via `payment` in podcast.yaml).

# paths./donate.post.parameters[].description
Optional x402 payment payload. If absent, the server replies 402 with paymentRequirements (the normal first step). If a client returns with this header carrying the encoded payment, the server replies 200 with a receipt.

# paths./donate.post.responses.200.description
Payment acknowledged. Returned when the request includes an `X-Payment` header carrying an encoded x402 payment payload. On-chain settlement is verified asynchronously via the facilitator endpoint.

# paths./donate.post.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./donate.post.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./donate.post.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./donate.post.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./donate.post.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./donate.post.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./donate.post.responses.402.description
Payment Required (first step — no `X-Payment` header sent).

# paths./donate.post.responses.402.headers.Link.description
RFC 8288 — rel=payment + rel=x402-supported.

# paths./episodes.json.get.description
Static JSON: every episode with id, title, date, duration, audio URL, etc.

# paths./episodes.json.get.parameters[].description
RFC 9110 conditional request. Server replies 304 if the catalog hasn't changed (Cloudflare Pages emits ETag).

# paths./episodes.json.get.responses.200.description
Array of episodes (sorted by id ascending).

# paths./episodes.json.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./episodes.json.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./episodes.json.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./episodes.json.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./episodes.json.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./episodes.json.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./search-index.json.get.description
Flat object mapping episode id → indexed text (title + description + transcript). Use /api/search for ranked queries; this is for offline indexing.

# paths./search-index.json.get.parameters[].description
RFC 9110 conditional request. Server replies 304 if the index hasn't changed.

# paths./search-index.json.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./search-index.json.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./search-index.json.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./search-index.json.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./search-index.json.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./search-index.json.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./rss.xml.get.description
RSS 2.0 feed with iTunes/Spotify extensions. Subscribe via any podcast app.

# paths./rss.xml.get.parameters[].description
RFC 9110 conditional request. Common for RSS clients to poll efficiently — server replies 304 when the feed is unchanged.

# paths./rss.xml.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./rss.xml.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./rss.xml.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./rss.xml.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./rss.xml.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./rss.xml.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./llms.txt.get.description
Markdown briefing for assistant agents — show identity, capabilities, latest episode, and pointers to all other agent surfaces.

# paths./llms.txt.get.parameters[].description
RFC 9110 conditional request. Server replies 304 if the briefing hasn't changed.

# paths./llms.txt.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./llms.txt.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./llms.txt.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./llms.txt.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./llms.txt.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./llms.txt.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./mcp.get.description
Returns the MCP server manifest (tools list, transport, protocol version).

# paths./mcp.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./mcp.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./mcp.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./mcp.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./mcp.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./mcp.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./mcp.post.description
Streamable HTTP transport for the Model Context Protocol. Methods: initialize, ping, tools/list, tools/call, resources/list, resources/read. Tools: search_episodes, get_episode, get_latest_episode. Batch / bulk: the request body may also be a JSON-RPC 2.0 batch — a non-empty array (max 50) of request objects executed in one round-trip; the response is an array of responses in the same order.

# paths./mcp.post.responses.200.description
A JSON-RPC 2.0 response, or — for a batch request — an array of responses in request order.

# paths./mcp.post.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./mcp.post.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./mcp.post.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./mcp.post.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./mcp.post.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./mcp.post.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./.well-known/mcp.get.description
Same as GET /mcp but at the well-known URL. Also accepts POST for live JSON-RPC handshake.

# paths./.well-known/mcp.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./.well-known/mcp.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./.well-known/mcp.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./.well-known/mcp.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./.well-known/mcp.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./.well-known/mcp.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./.well-known/mcp.post.description
Same JSON-RPC endpoint as /mcp; agents that probe well-known can initialize directly. Also accepts a JSON-RPC 2.0 batch (array of up to 50 request objects).

# paths./.well-known/mcp.post.responses.200.description
A JSON-RPC 2.0 response, or an array of responses for a batch request.

# paths./.well-known/mcp.post.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./.well-known/mcp.post.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./.well-known/mcp.post.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./.well-known/mcp.post.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./.well-known/mcp.post.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./.well-known/mcp.post.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./.well-known/mcp/server-card.json.get.description
Preview-able card describing this MCP server (name, version, tools[]) before opening a transport.

# paths./.well-known/mcp/server-card.json.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./.well-known/mcp/server-card.json.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./.well-known/mcp/server-card.json.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./.well-known/mcp/server-card.json.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./.well-known/mcp/server-card.json.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./.well-known/mcp/server-card.json.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# paths./.well-known/api-catalog.get.description
Linkset enumerating all agent-accessible APIs and service descriptions.

# paths./.well-known/api-catalog.get.responses.200.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# paths./.well-known/api-catalog.get.responses.200.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# paths./.well-known/api-catalog.get.responses.200.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# paths./.well-known/api-catalog.get.responses.200.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# paths./.well-known/api-catalog.get.responses.200.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# paths./.well-known/api-catalog.get.responses.200.headers.API-Version.description
The API contract version that served this response (date-based).

# components.parameters.ApiVersion.description
Pins the API contract version (date-based). The current and only supported version is 2026-05-18; the same value is returned in the API-Version response header. See info.x-deprecation-policy for how versions are retired.

# components.parameters.BatchSize.description
Batch convention — preferred per-batch item count when chunking large workloads against a REST bulk endpoint. Reserved for future bulk endpoints; see info.x-batch and the BatchRequest / BatchResponse schemas.

# components.parameters.IdempotencyKey.description
Client-supplied retry-safety key. Send a stable opaque string on each mutation request; replays of the same key are processed at most once. The server echoes the key back in the response `Idempotency-Key` header so callers can correlate retries. For async endpoints (POST /jobs, POST /ask?async=1, POST /api/search?async=1), the key is folded into the job id derivation so the same key + body deterministically returns the same job id without server-side state.

# components.schemas.EpisodeList.description
Full episode list, sorted by id ascending.

# components.schemas.SearchIndex.description
Episode-id (string key) → searchable text (title + description + transcript).

# components.schemas.RssFeed.description
RSS 2.0 feed XML body, conforming to iTunes and Spotify podcast extensions.

# components.schemas.RssFeed.example
<?xml version="1.0" encoding="UTF-8"?><rss version="2.0">…</rss>

# components.schemas.LlmsTxt.description
Plain-text llms.txt briefing per llmstxt.org. Markdown structure with explicit sections for Agent instructions, Find <show>, About, Why, Use cases, Constraints, Topics, Capabilities, Data & APIs, Subscribe, Latest episode.

# components.schemas.ApiCatalog.description
RFC 9727 linkset enumerating agent-accessible APIs and service descriptions.

# components.schemas.WebhookEvent.description
Delivery payload POSTed to a subscribed callback.

# components.schemas.McpManifest.properties.batch.description
JSON-RPC 2.0 batch capability — POST an array of request objects to /mcp.

# components.schemas.JsonRpcRequest.properties.id.description
JSON-RPC request id; echoed in the response. May also be JSON null per the JSON-RPC 2.0 spec.

# components.schemas.JsonRpcRequest.properties.method.description
Method name (e.g. initialize, tools/list, tools/call).

# components.schemas.JsonRpcResponse.properties.id.description
Echoes the request id. May also be JSON null when the request id was null.

# components.schemas.JsonRpcResponse.properties.result.description
Method-specific success payload (shape depends on method).

# components.schemas.JsonRpcBatchRequest.description
JSON-RPC 2.0 batch — a non-empty array of request objects executed in a single round-trip. The server answers with an array of responses in the same order. Capped at 50 requests per batch.

# components.schemas.JsonRpcBatchResponse.description
Array of JSON-RPC 2.0 responses, one per batch request, in request order.

# components.schemas.BatchRequest.description
REST batch / bulk request envelope. Reserved for future bulk endpoints; current REST surfaces are single-resource. The JSON-RPC batch convention used by /mcp is separately defined in JsonRpcBatchRequest.

# components.schemas.BatchRequest.properties.items.description
Per-item payloads to process in this batch. Order is preserved in the response.

# components.schemas.BatchItemResult.description
Result for a single item in a batch / bulk response.

# components.schemas.BatchItemResult.properties.index.description
0-based position of this item in the request `items` array.

# components.schemas.BatchItemResult.properties.status.description
Per-item outcome — items succeed or fail independently.

# components.schemas.BatchItemResult.properties.data.description
The single-item response payload when `status: succeeded`. Omitted on failure.

# components.schemas.BatchItemResult.properties.error.description
Typed error when `status: failed`. Omitted on success.

# components.schemas.BatchResponse.description
REST batch / bulk response envelope. Carries one result per input item; items succeed or fail independently. The top-level HTTP status is 200 unless the whole call could not be processed.

# components.schemas.BatchResponse.properties.results.description
Per-item results in the same order as the request `items` array.

# components.schemas.DonateReceipt.properties.settled.description
On-chain settlement confirmed (verified by facilitator).

# components.schemas.JobSpec.properties.query.description
The natural-language query (for kind=ask) or search keywords (for kind=search).

# components.schemas.JobCreated.description
Body returned with HTTP 202 Accepted on every async entry point.

# components.schemas.JobCreated.properties.job_id.description
Opaque, stateless job id — encodes the spec.

# components.schemas.JobCreated.properties.poll_url.description
GET this URL until status is `completed`.

# components.schemas.JobCreated.properties.retry_after_seconds.description
Mirrors the Retry-After response header.

# components.schemas.JobBatchResponse.description
Response envelope for POST /jobs/batch — array of per-item job entries.

# components.schemas.JobBatchResponse.properties.failed.description
Number of items rejected at validation time.

# components.schemas.JobBatchResponse.properties.idempotency_key.description
Echo of the request-wide Idempotency-Key header when present.

# components.schemas.JobStatus.properties.result.description
Present when status is `completed`. Shape mirrors the synchronous endpoint for the same `kind`.

# components.schemas.JobsDiscovery.description
Discovery envelope returned by GET /jobs describing the 202 Accepted async pattern.

# components.schemas.JobsDiscovery.properties.pattern.description
The async pattern in use, e.g. '202 Accepted + poll'.

# components.schemas.JobsDiscovery.properties.poll_url_template.description
RFC 6570 template for the polling URL, e.g. /jobs/{id}.

# components.schemas.JobsDiscovery.properties.example.description
Example request/response pair for the async flow.

# components.schemas.JobsBatchDiscovery.description
Discovery envelope returned by GET /jobs/batch describing the array-body batch surface.

# components.schemas.JobsBatchDiscovery.properties.request_schema.description
Pointer to the request schema (array of JobSpec).

# components.schemas.JobsBatchDiscovery.properties.response_schema.description
Pointer to the response schema (JobBatchResponse).

# components.schemas.WebhookCatalog.description
Webhook event catalog returned by GET /webhooks.

# components.schemas.WebhookCatalog.properties.payload_schema.description
JSON Schema of the delivery payload (see WebhookEvent).

# components.schemas.McpResponse.description
A single JSON-RPC 2.0 response, or — for a batch request — an array of responses in request order.

# components.schemas.Error.description
Canonical error envelope. Every 4xx and 5xx response serves this schema, both as application/json and application/problem+json (RFC 7807). The wrapping `error` object groups the machine-readable fields so envelopes are forward-compatible with adding sibling keys (meta, debug, trace_id) without breaking existing parsers.

# components.responses.NotModified.description
The conditional GET matched the current ETag (or Last-Modified). Body is empty. Cloudflare Pages emits this automatically for static assets.

# components.responses.NotModified.headers.ETag.description
Strong validator. Reuse in If-None-Match on the next request.

# components.responses.BadRequest.description
The request was malformed (missing/invalid parameter, bad body).

# components.responses.BadRequest.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# components.responses.BadRequest.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# components.responses.BadRequest.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# components.responses.BadRequest.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# components.responses.BadRequest.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# components.responses.BadRequest.headers.API-Version.description
The API contract version that served this response (date-based).

# components.responses.NotFound.description
The requested resource doesn't exist on this show.

# components.responses.NotFound.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# components.responses.NotFound.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# components.responses.NotFound.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# components.responses.NotFound.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# components.responses.NotFound.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# components.responses.NotFound.headers.API-Version.description
The API contract version that served this response (date-based).

# components.responses.MethodNotAllowed.description
The HTTP method isn't supported on this endpoint.

# components.responses.MethodNotAllowed.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# components.responses.MethodNotAllowed.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# components.responses.MethodNotAllowed.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# components.responses.MethodNotAllowed.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# components.responses.MethodNotAllowed.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# components.responses.MethodNotAllowed.headers.API-Version.description
The API contract version that served this response (date-based).

# components.responses.RateLimited.description
Rate limit exceeded. Inspect Retry-After / X-RateLimit-* headers.

# components.responses.RateLimited.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# components.responses.RateLimited.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# components.responses.RateLimited.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# components.responses.RateLimited.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# components.responses.RateLimited.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# components.responses.RateLimited.headers.API-Version.description
The API contract version that served this response (date-based).

# components.responses.InternalError.headers.RateLimit-Remaining.description
RFC 9598. Requests remaining in current window.

# components.responses.InternalError.headers.RateLimit-Reset.description
RFC 9598. Seconds until the window resets (delta).

# components.responses.InternalError.headers.RateLimit-Policy.description
RFC 9598. The active rate-limit policy expressed as `<limit>;w=<window-seconds>`.

# components.responses.InternalError.headers.X-RateLimit-Remaining.description
Legacy. Same value as RateLimit-Remaining.

# components.responses.InternalError.headers.X-RateLimit-Reset.description
Legacy. Unix timestamp when the window resets.

# components.responses.InternalError.headers.API-Version.description
The API contract version that served this response (date-based).