API and SDK

API and Node SDK

Cascade can be integrated programmatically through the npm package or through its OpenAI-compatible HTTP adapter. Both use the same underlying orchestration engine; the /v1 endpoints are not a second independent agent pipeline.

Node SDK

Install Node.js 22.22.2+ and the package:

npm install cascade-ai

import { runCascade, createCascade, streamCascade } from 'cascade-ai';

const result = await runCascade('Explain this module');
console.log(result.output);

await streamCascade('Summarize the codebase', token => process.stdout.write(token));

const cascade = createCascade({
  providers: [{ type: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY }],
});
await cascade.init();
const report = await cascade.run({ prompt: 'Propose integration tests' });

The SDK has lifecycle events, streamed output and cancellation through AbortSignal. Host applications must supply appropriate credential storage and tool-approval handling. See the SDK examples.

OpenAI-compatible /v1 HTTP adapter

Endpoint	Function
GET /v1/models	Discover Cascade routing identifiers
POST /v1/chat/completions	Execute a buffered or streamed orchestration run

The request's model is a Cascade routing mode, not the name of an individual provider model.

Identifier	Behavior
cascade	Auto/balanced orchestration
cascade-fast	Quick response without full hierarchy
cascade-quality	Quality-biased routing

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CASCADE_ACCESS_TOKEN",
    base_url="http://localhost:8787/v1",
)
reply = client.chat.completions.create(
    model="cascade",
    messages=[{"role": "user", "content": "Compare SQLite and PostgreSQL."}],
)
print(reply.choices[0].message.content)

Use a Cascade access token, not a vendor API key, for /v1 bearer authentication. Provider keys are optionally sent as request provider settings; self-host operator environment keys are considered only for a single-account instance, not once a second account exists.

Deliberate compatibility limits

• Unsupported model identifiers return 404 model_not_found rather than silently substituting another mode.
• Unsupported OpenAI request features (including arbitrary tool/function calling and some output parameters) are rejected rather than ignored.
• The HTTP adapter is noninteractive: human approvals, escalation questions and other interactive gates use unattended defaults rather than waiting for a browser response.
• Browser-side SDK requests are not automatically granted permissive cross-origin access.

Implementation: cloud/server/src/openai-compat.ts. Design notes: docs/openai-compat.md.