REST API

The API does one thing end to end: you submit a brief, poll until the search is done, then fetch the results as JSON or CSV. A submitted search can't be changed afterwards — to search differently, submit a new brief. Every search draws on your workspace's credits and budget limits exactly as a search started from Slack does.

1. Mint an API key

In Orbit, go to Settings → Workspace → API (/settings/workspace/api) and create a new key. It looks like ok_live_… and is shown exactly once — store it in a secret manager. Keys are secrets: call the API from your server, never from a browser or mobile app.

The base URL for every request:

https://api.orbitpeople.ai/v1

2. Submit a brief

curl -X POST https://api.orbitpeople.ai/v1/search \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brief": "Senior fintech engineers in Berlin with payments experience"}'

Response (202 Accepted):

{ "projectId": "abc123", "status": "running" }

3. Poll for completion

curl https://api.orbitpeople.ai/v1/projects/abc123 \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "projectId": "abc123",
  "status": "running",
  "done": false,
  "totalResults": 14,
  "verifiedResults": 11,
  "requestedTarget": null,
  "starredResults": 0,
  "clarificationQuestion": null,
  "error": null
}

Poll every few seconds until done is true — a search that found nobody finishes too, with totalResults: 0. If status is "awaiting_input", Orbit couldn't act on the brief as written and clarificationQuestion says why — the API can't answer it, so submit a new, more specific brief.

4. Retrieve results

curl "https://api.orbitpeople.ai/v1/projects/abc123/results?limit=100&offset=0" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "projectId": "abc123",
  "total": 42,
  "limit": 100,
  "offset": 0,
  "results": [
    {
      "fullName": "Alice Müller",
      "firstName": "Alice",
      "lastName": "Müller",
      "title": "Senior Software Engineer",
      "company": "Finleap",
      "location": "Berlin, Germany",
      "linkedinUrl": "https://linkedin.com/in/alice-mueller",
      "primaryEmail": "alice@finleap.com",
      "primaryPhone": null,
      "surfacedBy": "Berlin fintech engineers",
      "starred": false,
      "fields": {},
      "verdicts": { "Payments experience": "yes" }
    }
  ]
}

What each field means: Reading results.

5. Export CSV

curl https://api.orbitpeople.ai/v1/projects/abc123/export.csv \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -o results.csv

Byte-identical to Orbit's in-app export.

Skip polling with webhooks

Pass callbackUrl and Orbit POSTs a signed project.completed event when the search finishes. See Webhooks.

curl -X POST https://api.orbitpeople.ai/v1/search \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Senior fintech engineers in Berlin",
    "callbackUrl": "https://yourapp.com/webhooks/orbit"
  }'

Error responses

All errors follow { "error": { "code": "...", "message": "..." } }:

Code	HTTP	Meaning
`unauthorized`	401	Missing, invalid or revoked API key
`not_found`	404	No such project in your workspace, or no such endpoint
`invalid_request`	400	Bad request body or query parameters
`limit_exceeded`	429	With a `Retry-After` header: too many requests — wait that many seconds and repeat. Without one: the workspace's budget or credit balance is used up, which waiting won't fix
`internal_error`	500	Transient server error — safe to retry

Limits

120 requests a minute per API key, across every endpoint. Polling every few seconds is well inside it.
20 new searches an hour per workspace, however many keys it has.

Past either, you get 429 limit_exceeded with a Retry-After header in seconds. Wait it out and repeat the request — nothing was lost.

The live OpenAPI spec

GET https://api.orbitpeople.ai/v1/openapi.json

Unauthenticated. Import it into any code generator or API client, or browse the interactive reference.

On this page