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/sdk2. 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 exportSkip 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
5xxare retried for you, twice by default (maxRetrieschanges it;0turns it off). limit_exceededwith aRetry-Afteris 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: 0if a duplicate search is worse than retrying by hand. waitForCompletionthrowsOrbitTimeoutErroroncetimeoutMspasses.
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.
}
}