Missing response headers in swagger.yaml

[13rac1]

The OpenAPI spec (swagger.yaml) is missing response header declarations on most endpoints. The API Reference [permalink] documents ~30 response headers, but the swagger only declares headers on a handful of image endpoints.

Probing methodology

We probed 36 endpoints with curl -D on 2026-06-06, capturing all response headers. Endpoints requiring wallet auth (x402) or file uploads that returned 400 are noted but excluded from the analysis.

Returned on all inference/augment POST endpoints

These 5 headers were returned on every successful POST to /chat/completions, /responses, /embeddings, /images/generations, /audio/speech, /augment/search, and /augment/scrape:

Header	Type	Description
x-venice-version	string	API server version
x-venice-balance-usd	string	USD balance
x-ratelimit-limit-requests	integer	Max requests in current window
x-ratelimit-remaining-requests	integer	Requests remaining in current window
x-ratelimit-reset-requests	integer	Unix timestamp when request limit resets

Returned on token-based endpoints only

These 3 headers were returned on /chat/completions, /responses, and /embeddings:

Header	Type	Description
x-ratelimit-limit-tokens	integer	Max tokens in current window
x-ratelimit-remaining-tokens	integer	Tokens remaining in current window
x-ratelimit-reset-tokens	integer	Unix timestamp when token limit resets

Returned on image generation only

These 2 headers were returned on /images/generations:

Header	Type	Description
x-venice-is-blurred	string (true/false)	Whether the image was blurred (Safe Venice)
x-venice-is-content-violation	string (true/false)	Whether content violated ToS

Returned on paginated endpoints only

These 4 headers were returned on /characters/{slug}/reviews:

Header	Type	Description
x-pagination-limit	integer	Items per page
x-pagination-page	integer	Current page number
x-pagination-total	integer	Total items
x-pagination-total-pages	integer	Total pages

Headers documented in api-spec.mdx but not observed

The following headers are listed in the Response Headers Reference but were not returned on any probed endpoint:

Header	Documented as	Notes
x-venice-balance-diem	All authenticated requests	Only x-venice-balance-usd was returned
x-venice-model-id	Inference endpoints	Not returned on chat/completions, embeddings, images/generations, or audio/speech
x-venice-model-name	Inference endpoints	Same
x-venice-model-router	Inference endpoints	Same
x-venice-timestamp	When timestamp tracking is enabled	Not observed
x-venice-host-name	Error responses	Not observed on 400/401/404 responses
x-ratelimit-type	When rate limiting is enforced	Not observed
x-venice-model-deprecation-warning	Deprecated models	Not tested (no deprecated model used)
x-venice-model-deprecation-date	Deprecated models	Same
x-venice-is-adult-model-content-violation	Image generation	May require specific content to trigger
x-venice-contains-minor	Image analysis	May require specific content to trigger

GET endpoints return no Venice headers

None of the GET endpoints (/models, /models/traits, /characters, /image/styles, /billing/usage-analytics, /api_keys/rate_limits, /crypto/rpc/networks) returned any x-venice-* or x-ratelimit-* headers. Only cf-ray was present.

Current swagger.yaml coverage

The swagger currently [permalink] declares response headers only on these endpoints:

• POST /image/generate (200) — x-venice-is-blurred, x-venice-is-content-violation, x-venice-model-deprecation-warning, x-venice-model-deprecation-date, x-venice-deprecated, x-venice-deprecated-replacement
• POST /images/generations (200) — same as above
• POST /image/edit (200) — same plus x-venice-model-id, x-venice-model-name, X-Balance-Remaining
• POST /crypto/rpc/{network} (200) — X-Venice-RPC-Credits, X-Venice-RPC-Cost-USD, X-Balance-Remaining, X-Request-ID
• Various endpoints (402) — PAYMENT-REQUIRED, X-Balance-Remaining

All other endpoints have no headers: block in their response definitions.

Request

Please add response header declarations to the swagger for all endpoints that return them, matching the observed behavior above.

[joshua-mo-143]

Thanks for reaching out @13rac1, I'll get this fixed.

[13rac1]

Cool! Thank you