Documentation

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,
});

from crosmos import Crosmos

client = Crosmos(
    api_key="csk_...",
    base_url="https://api.crosmos.dev",
    timeout=60.0,  # seconds, not milliseconds
    max_retries=2,
)

Python uses snake_case equivalents: apiKey → api_key, baseURL → base_url, maxRetries → max_retries.

Option	Description	Default
`apiKey` / `api_key`	JWT access token or Crosmos API key.	`CROSMOS_API_KEY`
`baseURL` / `base_url`	API base URL.	`CROSMOS_BASE_URL` or `https://api.crosmos.dev`
`timeout`	Request timeout. TypeScript: milliseconds. Python: seconds.	`60000` / `60.0`
`maxRetries` / `max_retries`	Retry attempts for transient failures.	`2`
`fetch` / `http_client`	Custom HTTP client. TypeScript: fetch. Python: `httpx.Client`.	global `fetch` / `httpx.Client`
`defaultHeaders` / `default_headers`	Headers sent with every request.	none
`defaultQuery` / `default_query`	Query parameters sent with every request.	none
`logLevel`	SDK log level (TypeScript only).	`CROSMOS_LOG` or `warn`
`logger`	Logger instance (TypeScript only).	`console`

Environment variables

Variable	Description
`CROSMOS_API_KEY`	API key used when `apiKey` / `api_key` is not passed directly.
`CROSMOS_BASE_URL`	API base URL used when `baseURL` / `base_url` is not passed directly.
`CROSMOS_LOG`	Log level: `debug`, `info`, `warn`, `error`, or `off`.
`CROSMOS_CUSTOM_HEADERS`	Newline-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",
		},
	},
);

search = client.search.hybrid(
    space_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    query="What does the user prefer for TypeScript projects?",
    timeout=10.0,
    max_retries=5,
    extra_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;

scoped = client.with_options(max_retries=5, timeout=10.0)

search = scoped.search.hybrid(
    space_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    query="What changed since yesterday?",
)

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,
});

client = Crosmos(max_retries=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,
	},
);

client.search.hybrid(
    space_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    query="What does the user remember about Austin?",
    max_retries=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;
}

from crosmos import APIError

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

    print(search.candidates)
except APIError as e:
    print(e.status_code)
    print(e.message)
    raise

Status	Error class
`400`	`BadRequestError`
`401`	`AuthenticationError`
`403`	`PermissionDeniedError`
`404`	`NotFoundError`
`409`	`ConflictError`
`422`	`UnprocessableEntityError`
`429`	`RateLimitError`
`>=500`	`InternalServerError`
no response	`APIConnectionError` 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);

response = client.search.with_raw_response.hybrid(
    space_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    query="What does the user prefer?",
)

print(response.headers.get("X-Request-Id"))
search = response.parse()  # returns typed Search object
print(search.candidates)

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);

with client.search.with_streaming_response.hybrid(
    space_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    query="What does the user prefer?",
) as response:
    print(response.status_code)
    for line in response.iter_lines():
        print(line)

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,
});

import httpx
from crosmos import Crosmos, DefaultHttpxClient

client = Crosmos(
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy:8080",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

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?",
    )

Getting Started

Concepts

MCP

SDKs

Advanced

Client options

Environment variables

Per-request options

Retries and timeouts

Handling errors

Raw responses

Pydantic responses

Custom HTTP client

Runtime support

​Client options

​Environment variables

​Per-request options

​Retries and timeouts

​Handling errors

​Raw responses

​Pydantic responses

​Custom HTTP client

​Runtime support

Client options

Environment variables

Per-request options

Retries and timeouts

Handling errors

Raw responses

Pydantic responses

Custom HTTP client

Runtime support