Orthogonal SDK

TypeScript SDK for calling APIs on the Orthogonal platform.

Call any API on the Orthogonal platform through one client and one credit balance — authentication, routing, and billing are handled for you.

Table of Contents

• Why Orthogonal
• Installation
• Quick Start
• Authentication
• Usage
• Error Handling
• API Reference
• TypeScript
• Related
• License

Why Orthogonal

Orthogonal puts a catalog of APIs behind one account and one balance:

• One integration — call any API on the platform through a single run() method.
• Pay per use — a single credit balance instead of juggling dozens of provider subscriptions.
• Self-correcting errors — failed calls carry a structured hint (expected schema, unexpected/missing fields, numeric bounds) so agents can fix and retry.
• Fully typed — ships with TypeScript definitions and ESM + CJS builds.

Installation

Requires Node.js 18+.

npm install @orth/sdk
# or: pnpm add @orth/sdk  /  yarn add @orth/sdk

Quick Start

import Orthogonal from "@orth/sdk";

const orthogonal = new Orthogonal({
  apiKey: process.env.ORTHOGONAL_API_KEY!,
});

const res = await orthogonal.run({
  api: "tavily",
  path: "/search",
  query: { query: "latest AI news" },
});

console.log(res.data);   // the upstream API's response
console.log(res.price);  // amount charged, e.g. "0.01"

Get an API key from your Orthogonal dashboard.

Authentication

Pass your key to the constructor:

const orthogonal = new Orthogonal({ apiKey: "orth_live_your_key" });

Prefer reading it from the environment so keys never live in source:

const orthogonal = new Orthogonal({ apiKey: process.env.ORTHOGONAL_API_KEY! });

Usage

GET request (query params)

const res = await orthogonal.run({
  api: "fantastic-jobs",
  path: "/v1/active-ats",
  query: { time_frame: "1h", limit: 10 },
});

POST request (JSON body)

const res = await orthogonal.run({
  api: "some-api",
  path: "/v1/generate",
  body: { prompt: "a red bicycle" },
});

Custom headers

Headers passed to the constructor are sent on every request:

const orthogonal = new Orthogonal({
  apiKey: process.env.ORTHOGONAL_API_KEY!,
  headers: { "x-my-trace-id": "abc123" },
});

Error Handling

run() resolves with the response on success and throws an OrthogonalRunError on any non-2xx response. The error extends Error (so error.message and instanceof Error work) and carries structured details:

import Orthogonal, { OrthogonalRunError } from "@orth/sdk";

try {
  const res = await orthogonal.run({
    api: "fantastic-jobs",
    path: "/v1/active-ats",
    query: { time_frame: "1h", company: "Google" }, // wrong field name
  });
} catch (err) {
  if (err instanceof OrthogonalRunError) {
    console.error(err.message);          // human-readable summary
    console.error(err.status);           // HTTP status, e.g. 400
    console.error(err.orthogonal);       // self-correction hint (see below)
    console.error(err.responseBody);     // full parsed error body
  }
}

On a contract violation the orthogonal hint tells you exactly what to fix — for example, that company is an unexpected field and organization is the expected one, plus the endpoint's expected schema — so an agent can correct the request and retry instead of repeating a failing call.

API Reference

new Orthogonal(config)

Option	Type	Description
apiKey	string	Required. Your Orthogonal API key (orth_live_… / orth_test_…).
headers	Record<string, string>	Optional headers sent on every request.

orthogonal.run(options) → Promise<RunResponse>

Option	Type	Description
api	string	Required. The API slug (e.g. "tavily").
path	string	Required. The endpoint path (e.g. "/search").
query	Record<string, unknown>	Query parameters.
body	Record<string, unknown>	Request body for POST/PUT/PATCH.

RunResponse

Field	Type	Description
success	boolean	Whether the call succeeded.
price	string	Amount charged in USD (e.g. "0.01").
data	unknown	The upstream API's response.

OrthogonalRunError

Thrown by run() on a non-2xx response. Extends Error.

Property	Type	Description
status	number	HTTP status of the failed response.
orthogonal	unknown	Self-correction hint (expected schema, unexpected/missing fields), when present.
responseBody	unknown	The full parsed response body.

TypeScript

The package ships with type definitions and both ESM and CommonJS builds — no @types package needed. All options and responses (OrthogonalConfig, RunOptions, RunResponse) are exported.

Related

• @orth/cli — the Orthogonal command-line tool.
• orth — the official Python SDK.

License

MIT © Orthogonal