SDK overview

The checked-in SDKs expose the complete public REST surface with typed resources, bearer authentication, response-envelope validation, timeouts, idempotency, and structured errors. TypeScript also supports AbortSignal cancellation. They are distributed through the private registry configured for your organization; the repository does not publish them automatically.

Both clients read COMBINED_TOKEN and COMBINED_API_URL by default. You can pass constructor options explicitly when a service has its own secret provider.

Shared behavior

• The base URL must be an HTTPS origin with no path, query, fragment, or embedded credentials. Plain HTTP is allowed only for localhost development.
• The default request timeout is 30 seconds.
• Mutations get a secure random idempotency key unless one is supplied in request options.
• GET requests retry once for 429, 502, 503, or 504. Mutations and SQL are never automatically retried.
• Retry-After is honored up to five seconds; otherwise the retry delay is 250 ms.
• Success envelopes are validated before data is returned.
• API failures become ContextOSError with status, code, correlationId/correlation_id, and optional details.

Resource map

The clients expose accounts, activity, catalogue, connector definitions, grants, query receipts, schema reviews, Source authorization requests, Sources, and SQL. See Resource methods for every method and its REST operation.

Use the SDK for application code, MCP for tool-using agents, and the web Query workspace for interactive investigation. All three enforce the same account and grant boundaries.