REST API

1. Mint an API key

In Orbit, go to Settings → API keys and create a new key. It looks like ok_live_… and is shown exactly once — store it in a secret manager.

The API base URL is your deployment origin followed by /v1:

https://<your-deployment>.convex.site/v1

2. Submit a brief

curl -X POST https://<your-deployment>.convex.site/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" }

3. Poll for completion

curl https://<your-deployment>.convex.site/v1/projects/abc123 \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "projectId": "abc123",
  "status": "running",
  "done": false,
  "resultCount": 14,
  "relevantCount": 11,
  "irrelevantCount": 2,
  "unknownCount": 1,
  "requestedTarget": null,
  "clarificationQuestion": null,
  "error": null
}

Poll until done: true. If status becomes "awaiting_input", Orbit has a clarification question — answer it in the Orbit UI then resume.

4. Retrieve results

curl "https://<your-deployment>.convex.site/v1/projects/abc123/results?limit=100&offset=0" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "total": 42,
  "offset": 0,
  "limit": 100,
  "results": [
    {
      "resultId": "r1",
      "fullName": "Alice Müller",
      "title": "Senior Software Engineer",
      "company": "Finleap",
      "location": "Berlin, Germany",
      "linkedinUrl": "https://linkedin.com/in/alice-mueller",
      "email": "alice@finleap.com",
      "emailStatus": "verified",
      "verdict": "relevant",
      "verdictReason": "Payments-focused engineer at a Berlin fintech, 6 years experience",
      "starred": false,
      "surfacedBy": "open-web search"
    }
  ]
}

Filter on verdict === "relevant" for your short list. Review "unknown" results for borderline cases.

5. Export CSV

curl https://<your-deployment>.convex.site/v1/projects/abc123/results.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 project finishes. See Webhooks.

curl -X POST .../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 or invalid API key
`not_found`	404	Project doesn't exist or belongs to another workspace
`invalid_request`	400	Bad request body or params
`limit_exceeded`	402	Workspace budget or credit cap
`rate_limited`	429	Too many requests
`internal_error`	500	Transient server error

The live OpenAPI spec

GET https://<your-deployment>.convex.site/v1/openapi.json

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

On this page