Orbitdocs

TypeScript SDK

npm i @orbitpeople/sdk — submit a brief, wait for the search, read typed results.

@orbitpeople/sdk is the typed client for the REST API. It adds the waiting and paging for you, retries network errors and server faults, and ships types for every request and response. Node 20 or later; no dependencies.

1. Install

npm i @orbitpeople/sdk

2. Mint an API key

In Orbit, go to Settings → Workspace → API (/settings/workspace/api) and create a key. It looks like ok_live_… and is shown once. Keys are secrets: use the SDK on your server, never in a browser or mobile app.

3. Search and read the results

import { OrbitClient } from "@orbitpeople/sdk";

const orbit = new OrbitClient({ apiKey: process.env.ORBIT_API_KEY! });

const { projectId } = await orbit.search({
  brief: "Senior fintech engineers in Berlin with payments experience",
});

const status = await orbit.waitForCompletion(projectId, {
  timeoutMs: 10 * 60 * 1000,
});

if (status.status === "awaiting_input") {
  // Orbit couldn't act on the brief as written — submit a sharper one.
  console.log(status.clarificationQuestion);
} else {
  for await (const person of orbit.listAllResults(projectId)) {
    console.log(person.fullName, person.title, person.linkedinUrl);
  }
}

What each field means: Reading results.

Export CSV

const csv = await orbit.exportCsv(projectId); // same file as the in-app export

Skip waiting with webhooks

Pass callbackUrl to search and Orbit POSTs a signed project.completed event when the search finishes. Check the signature before you trust it:

import { verifyWebhookSignature, type CallbackEvent } from "@orbitpeople/sdk";

// rawBody is the request body exactly as received, before any JSON parsing.
const valid = await verifyWebhookSignature({
  payload: rawBody,
  signature: request.headers.get("x-orbit-signature") ?? "",
  secret: process.env.ORBIT_WEBHOOK_SECRET!,
});
if (!valid) return new Response("bad signature", { status: 401 });

const event = JSON.parse(rawBody) as CallbackEvent;

More in Webhooks.

Errors and retries

A failed request throws OrbitApiError, carrying the API's code (unauthorized, not_found, invalid_request, limit_exceeded, internal_error — the same codes as the REST API).

  • Network errors and 5xx are retried for you, twice by default (maxRetries changes it; 0 turns it off).
  • limit_exceeded with a Retry-After is the request-rate limit: the SDK waits and retries. Without one, your workspace's budget or credits are used up — waiting won't fix it, so it throws straight away.
  • A network error after the server accepted a search is retried too, which can start it twice — pass maxRetries: 0 if a duplicate search is worse than retrying by hand.
  • waitForCompletion throws OrbitTimeoutError once timeoutMs passes.
import { OrbitApiError } from "@orbitpeople/sdk";

try {
  await orbit.search({ brief });
} catch (error) {
  if (error instanceof OrbitApiError && error.code === "limit_exceeded") {
    // Top up credits or raise the workspace budget, then search again.
  }
}

On this page