Skip to main content
Use this page when you need to tune SDK behavior beyond the default authenticated setup. Options apply to both the TypeScript and Python SDKs; where they differ, both are shown.

​
Client options

import Crosmos from "crosmos";

const client = new Crosmos({
	apiKey: process.env.CROSMOS_API_KEY,
	baseURL: "https://api.crosmos.dev",
	timeout: 60_000,
	maxRetries: 2,
});
Python uses snake_case equivalents: apiKey → api_key, baseURL → base_url, maxRetries → max_retries.
OptionDescriptionDefault
apiKey / api_keyJWT access token or Crosmos API key.CROSMOS_API_KEY
baseURL / base_urlAPI base URL.CROSMOS_BASE_URL or https://api.crosmos.dev
timeoutRequest timeout. TypeScript: milliseconds. Python: seconds.60000 / 60.0
maxRetries / max_retriesRetry attempts for transient failures.2
fetch / http_clientCustom HTTP client. TypeScript: fetch. Python: httpx.Client.global fetch / httpx.Client
defaultHeaders / default_headersHeaders sent with every request.none
defaultQuery / default_queryQuery parameters sent with every request.none
logLevelSDK log level (TypeScript only).CROSMOS_LOG or warn
loggerLogger instance (TypeScript only).console

​
Environment variables

VariableDescription
CROSMOS_API_KEYAPI key used when apiKey / api_key is not passed directly.
CROSMOS_BASE_URLAPI base URL used when baseURL / base_url is not passed directly.
CROSMOS_LOGLog level: debug, info, warn, error, or off.
CROSMOS_CUSTOM_HEADERSNewline-separated custom headers in Name: value format.
The SDK uses CROSMOS_BASE_URL. The MCP server uses CROSMOS_API_BASE_URL.

​
Per-request options

Most SDK methods accept per-request overrides. 
const search = await client.search.hybrid(
	{
		space_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		query: "What does the user prefer for TypeScript projects?",
	},
	{
		timeout: 10_000,
		maxRetries: 5,
		headers: {
			"X-Request-Source": "agent-worker",
		},
	},
);
Use AbortController (TypeScript) or client.with_options() (Python) when you need to cancel a request or create a scoped client copy: 
const controller = new AbortController();

const request = client.search.hybrid(
	{
		space_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		query: "What changed since yesterday?",
	},
	{
		signal: controller.signal,
	},
);

controller.abort();

await request;

​
Retries and timeouts

The SDK retries transient failures twice by default with exponential backoff and jitter. Retries apply to connection errors, request timeouts, 408, 409, 429, and 5xx responses. Disable retries globally: 
const client = new Crosmos({
	maxRetries: 0,
});
Tune retries for one request: 
await client.search.hybrid(
	{
		space_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		query: "What does the user remember about Austin?",
	},
	{
		maxRetries: 4,
	},
);

​
Handling errors

try {
	const search = await client.search.hybrid({
		space_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		query: "What is the user's preferred editor?",
	});

	console.log(search.candidates);
} catch (error) {
	if (error instanceof Crosmos.APIError) {
		console.log(error.status);
		console.log(error.name);
		console.log(error.headers);
		console.log(error.error);
		throw error;
	}

	throw error;
}
StatusError class
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
409ConflictError
422UnprocessableEntityError
429RateLimitError
>=500InternalServerError
no responseAPIConnectionError or APIConnectionTimeoutError

​
Raw responses

Every resource method returns a typed response. Use helper methods when you need the underlying HTTP response. 
const { data, response } = await client.search
	.hybrid({
		space_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		query: "What does the user prefer?",
	})
	.withResponse();

console.log(data.candidates);
console.log(response.headers);
Use .asResponse() (TypeScript) or .with_streaming_response (Python) when you only need the raw response without parsing: 
const response = await client.search
	.hybrid({
		space_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		query: "What does the user prefer?",
	})
	.asResponse();

console.log(response.status);

​
Pydantic responses

Python response objects are Pydantic models. Use .to_dict() and .to_json() to serialize them. 
search = client.search.hybrid(
    space_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    query="What does the user prefer?",
)

data = search.to_dict()    # dict
json_str = search.to_json()  # JSON string

​
Custom HTTP client

import Crosmos from "crosmos";
import fetch from "my-fetch";

const client = new Crosmos({
	fetch,
});
Use fetchOptions (TypeScript) for runtime-specific transport settings: 
const client = new Crosmos({
	fetchOptions: {
		// Runtime-specific RequestInit options go here.
	},
});

​
Runtime support

TypeScript: Uses the runtime’s global fetch implementation by default. Supports modern browsers, Node.js 20 LTS or later, Bun 1.0 or later, Deno 1.28 or later, Cloudflare Workers, Vercel Edge Runtime, Jest with the node environment, and Nitro 2.6 or later. React Native is not supported. Python: Supports Python 3.8 and later. Uses httpx for HTTP transport and pydantic for response validation. The AsyncCrosmos client uses anyio and is compatible with asyncio and trio. An optional aiohttp backend is available for projects already using aiohttp: 
from crosmos import AsyncCrosmos, DefaultAioHttpClient

async with AsyncCrosmos(http_client=DefaultAioHttpClient()) as client:
    search = await client.search.hybrid(
        space_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        query="What does the user prefer?",
    )