Table of Contents

• Why Orthogonal
• Installation
• Quick Start
• Authentication
• Usage
• Async Usage
• Error Handling
• API Reference
• 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.
• Sync and async — a blocking Orthogonal client and an await-able AsyncOrthogonal, both usable as context managers.
• Typed — RunOptions / RunResponse typed dicts and full type hints.

Installation

Requires Python 3.9+.

pip install orth

Quick Start

import os
from orthogonal import Orthogonal

with Orthogonal(api_key=os.environ["ORTHOGONAL_API_KEY"]) as orthogonal:
    res = orthogonal.run(
        api="tavily",
        path="/search",
        query={"query": "latest AI news"},
    )

print(res["data"])   # the upstream API's response
print(res["price"])  # amount charged, e.g. "0.01"

Get an API key from your Orthogonal dashboard.

Authentication

Pass your key to the constructor (reading it from the environment keeps keys out of source):

orthogonal = Orthogonal(api_key=os.environ["ORTHOGONAL_API_KEY"])

Usage

GET request (query params)

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

POST request (JSON body)

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

Options dict instead of keyword arguments

res = orthogonal.run({
    "api": "tavily",
    "path": "/search",
    "query": {"query": "hello world"},
})

Custom headers

Headers passed to the constructor are sent on every request:

orthogonal = Orthogonal(
    api_key=os.environ["ORTHOGONAL_API_KEY"],
    headers={"x-my-trace-id": "abc123"},
)

Async Usage

AsyncOrthogonal mirrors the sync client with await and async with:

import asyncio
from orthogonal import AsyncOrthogonal

async def main():
    async with AsyncOrthogonal(api_key=os.environ["ORTHOGONAL_API_KEY"]) as orthogonal:
        res = await orthogonal.run(
            api="tavily",
            path="/search",
            query={"query": "orthogonal"},
        )
        print(res["data"])

asyncio.run(main())

Error Handling

run() returns the response on success and raises OrthogonalError on any non-2xx response (invalid key, insufficient credits, or an upstream/validation error). The message describes what went wrong.

from orthogonal import Orthogonal, OrthogonalError

try:
    res = orthogonal.run(api="tavily", path="/search", query={"query": "x"})
except OrthogonalError as err:
    print(f"request failed: {err}")

API Reference

Orthogonal(api_key, *, headers=None, base_url=...)

orthogonal.run(options=None, *, api, path, query=None, body=None) → RunResponse

Call an endpoint. Pass either an options dict or keyword arguments (not both).

RunResponse (a TypedDict)

AsyncOrthogonal(...)

Same constructor and run(...) signature as Orthogonal, but run() is a coroutine (await) and the client supports async with / await client.close().

OrthogonalError

Raised by run() on a non-2xx response. Subclass of Exception; str(err) is a human-readable message.

Both clients are context managers — use with / async with (or call close()) so the underlying HTTP connection is released.

Related

• @orth/cli — the Orthogonal command-line tool.
• @orth/sdk — the official TypeScript/JavaScript SDK.

License

MIT © Orthogonal