Status: Stable. Generated from
api/v2/openapi.yamlbyscripts/derive-v2-api.py; do not edit.
Why this exists
Every non-standard header is named OpenWOP-<Name>, and every header is declared in OpenAPI. These tables are generated from that declaration, so they list all of them: a header not listed here is not part of the protocol.
Standard headers keep their standard names: Idempotency-Key, ETag, If-None-Match, Last-Event-ID, Retry-After, Authorization.
Request headers
| Header | Operations | Meaning |
|---|---|---|
Accept-Language | 1 | BCP-47 preference list; authoritative for locale selection (i18n.md). A malformed value MUST NOT produce a 400. |
Idempotency-Key | 18 | Per-mutation idempotency token (idempotency.md Layer 1). The server caches (tenantId, endpoint, key) → response for ≥24h. A duplicate request returns the cached response with OpenWOP-Idempotent-Replay: true. |
If-None-Match | 2 | Conditional request on the discovery document (capabilities.md §1) and the run snapshot (runs.md §Snapshot). A value that matches the current ETag (runs.md §Caching and encoding) MUST yield 304 Not Modified with no body. The 304 carries OpenWOP-Version like every response (versioning.md §1.4). |
Last-Event-ID | 1 | Resume from sequence after this ID. |
OpenWOP-Client-Version | 69 | The protocol version the client implements (versioning.md §1.5). Compared with minClientVersion on major.minor. A malformed value is treated as absent and MUST NOT produce a 400. Never selects a contract. |
OpenWOP-Dedup | 1 | When set, the host's cross-host claim system rejects a duplicate (tenantId, scopeId) pair with 409 Conflict. |
OpenWOP-Force-Engine-Version | 1 | Test keys only. The server emits this run's events as if it ran the given engine version, which must be within Capabilities.testing.forceEngineVersionRange. Servers MUST reject it on production API keys with 403 force_engine_version_forbidden. |
OpenWOP-Version | 69 | Selects one of the host's listed major.minor versions. Absent, /.well-known/openwop uses preferredVersion and every other unversioned path is v2; an unlisted value is 406 protocol_version_unsupported. |
Cross-origin preflight
A host granting an origin (Access-Control-Allow-Origin) in a CORS preflight for an operation MUST admit the operation's method in Access-Control-Allow-Methods and, in Access-Control-Allow-Headers, every request header api/v2/openapi.yaml declares for it, Authorization when it is authenticated and Content-Type when it takes a body, by listing them or by reflecting Access-Control-Request-Headers. A * does not admit Authorization. Which origins to grant, and whether with credentials, is host policy. Admitting this table's union on every operation conforms.
Response headers
| Header | Operations | Meaning |
|---|---|---|
Cache-Control | 2 | Standard HTTP caching directive (RFC 9111), set per operation: public content-page delivery, and prompt templates (immutable semantics when the version was pinned); see each operation. |
Content-Encoding | 1 | Present only when the host negotiated compression from Accept-Encoding; pairs with Vary: Accept-Encoding. The decoded body is byte-identical to the identity body. |
Content-Language | 1 | The BCP-47 locale actually used (equals the response locale). |
Content-Security-Policy | 1 | The plugin frame's isolation and egress policy. |
ETag | 3 | Standard HTTP validator (RFC 9110 §8.8.3). The obligation is per operation: MUST on the discovery document (capabilities.md §1), SHOULD on the run snapshot (runs.md §Snapshot), a content hash on a prompt template (getPromptTemplate); see each operation. |
Location | 1 | Canonical URI of the new template. |
OpenWOP-Idempotent-Replay | 1 | Set when the response was served from the idempotency cache. |
OpenWOP-Version | 69 | The contract that produced this response. It MUST equal the one used. |
Retry-After | 2 | Seconds until the active claim is stale-eligible. |
WWW-Authenticate | 62 | A Bearer challenge. On a host with an oauth2 or oidc lane it carries resource_metadata and error="invalid_token". Never sent on a non-disclosure 404. |
Webhook delivery headers
Declared in webhooks.md, not in OpenAPI, because the host is the client:
OpenWOP-Webhook-Id,OpenWOP-Event-Type,OpenWOP-Timestamp,OpenWOP-Signature,OpenWOP-Signature-Algorithm.- On a subscription that opted into Standard Webhooks (webhooks.md): that standard's
webhook-id,webhook-timestampandwebhook-signature, under their standard names. - During the v1 overlap only: the
X-openwop-*family, emitted beside them and removed at v1 end-of-support.
Removed in v2
These header names are not part of v2: Capabilities-Etag (use the standard ETag/If-None-Match pair), X-Dedup, X-Force-Engine-Version, X-Pack-Sha256, X-Pack-Signing-Method, X-openwop-* (webhooks), openwop-Webhook-Signature.
Sources: RFC 0165, RFC 0171, RFC 0172, RFC 0201.