SDKs · ORYVOX Docs

Language	Package	Source
Node.js / TypeScript (>= 18)	`@oryvox/sdk`	`sdks/node`
Python (>= 3.9)	`oryvox`	`sdks/python`

Both SDKs share one design:

	Node.js	Python
Client	`new Oryvox({ apiKey, baseURL, maxRetries, timeout, defaultHeaders })`	`Oryvox(api_key=, base_url=, max_retries=, timeout=, default_headers=)`, `AsyncOryvox(...)`
Env vars	`ORYVOX_API_KEY`, `ORYVOX_BASE_URL`	same
Responses	`client.responses.create()`, `client.responses.stream()`	`client.responses.create()`, `with client.responses.stream() as s:`
Chat	`client.chat.completions.create()`	`client.chat.completions.create()`
Models	`client.models.list()`	`client.models.list()`
Embeddings	`client.embeddings.create()`	`client.embeddings.create()`
Request log	`for await (const r of client.requests.list({ limit: 50, workflow_id }))`, `client.requests.retrieve(id)`	`for r in client.requests.list(limit=50, workflow_id=...):`, `client.requests.retrieve(id)`
Feedback	`client.requests.feedback(id, { rating: 5 })`	`client.requests.feedback(id, rating=5)`
Metrics	`client.metrics.retrieve({ period: '24h' })`	`client.metrics.retrieve(period="24h")`
Cache	`client.cache.invalidate({ tags: [...] })` / `({ all: true })`	`client.cache.invalidate(tags=[...])` / `(all=True)`
Webhooks	`Oryvox.webhooks.verify(payload, header, secret)`	`Oryvox.webhooks.verify(payload, header, secret)`
Test mode	`client.isTestMode`	`client.is_test_mode`
Request id	`result._requestId`	`result._request_id`
Idempotent replay	`result.idempotentReplayed`	`result.idempotent_replayed`

Defaults

Base URL https://api.oryvox.ai/v1
Timeout 60 seconds (Node: per attempt, whole body for normal calls and until the headers for streams; Python: per network operation)
2 retries

Per-call options

await client.responses.create(params, { idempotencyKey: 'order-42', timeout: 10_000, maxRetries: 0, headers: {}, signal });

client.responses.create(model="oryvox-auto", input="Hi", idempotency_key="order-42", timeout=10, max_retries=0, extra_headers={})

ORYVOX request headers have their own options:

Header	Node option	Python keyword
`X-Oryvox-Session`	`sessionId`	`session_id=`
`X-Oryvox-Trace-Id`	`traceId`	`trace_id=`
`X-Oryvox-Parent-Span`	`parentSpanId`	`parent_span_id=`
`X-Oryvox-Cache: off`	`cacheOff: true`	`cache_off=True`
`X-Oryvox-Cache-Scope`	`cacheScope`	`cache_scope=`

Retries

The SDKs retry only:

connection errors and timeouts,
HTTP 409, 429, 500, 502, 503 and 504, except a 409 with code ORYX_4092 (the key's request already ran and its result was not kept: retrying cannot help).

They never retry 400, 401, 402, 403, 404 or 422. Delays are exponential with jitter (0.5 s, 1 s, 2 s, 4 s, capped at 8 s, each shortened by up to 25%). When the response has a Retry-After header (seconds or HTTP date, up to 60 s) that value is used instead. The API sends Retry-After on its own rate limits; provider 429s passed through use backoff.

Every POST gets one Idempotency-Key (auto-generated unless you pass one) that is reused for all of its retries, so a retried request is never billed twice. Streams are only retried before the first byte arrives; a stream that breaks midway raises an error.

Errors

Both SDKs map API errors to typed classes; see Errors. Every error carries status, type, code and the request id. insufficient_credits raises InsufficientCreditsError, a subclass of BudgetExceededError.

Streaming

/responses streams yield typed events (response.created, response.output_text.delta, response.completed) and offer finalResponse() / finalText() (Node) or get_final_response() / get_final_text() (Python). Chat streams yield chat.completion.chunk objects and expose the oryvox summary as stream.summary. See Streaming.

Other languages

Any OpenAI-compatible SDK works with base_url=https://api.oryvox.ai/v1 and an ory_ key. ORYVOX extensions (routing, max_cost, optimization, metadata, tags, cache, oryvox) go in the request body (for example extra_body in the OpenAI Python SDK).

SDK versions: @oryvox/sdk 1.1.0 and oryvox 1.1.0 support everything in API 2026-10-04.