Skip to main content
Directory search is the primitive for private corpora in Orbit Search. To search private data, use an organization API key with search:read, grant that key access to the target directory, then pass the directory UUID in searchScope.

​
Find organization and directory IDs

You need two IDs for directory search setup:
  • organizationId — the organization that owns the directory.
  • directoryId — the private corpus to search.
When you create a directory, the create response returns both values: 
{
  "payload": {
    "id": "DIRECTORY_UUID",
    "org_id": "ORGANIZATION_UUID",
    "name": "Q4 Prospects"
  }
}
For an existing directory, list directories for the organization:
curl
curl "https://api.orbitsearch.com/v2/organizations/$ORGANIZATION_ID/directories" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
Use the returned id as DIRECTORY_ID. For multi-directory search, collect the id for each directory you want to search.

​
Grant directory access

An organization API key can search a directory only when a matching grant exists. For most developer integrations, grant either:
  • the whole organization, when all organization keys may search the directory
  • the specific API key, when one integration should have access
curl
curl -X POST "https://api.orbitsearch.com/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/grants" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "api_key",
    "principal_id": "API_KEY_UUID",
    "permission": "search"
  }'
API_KEY_UUID is the dashboard-visible key ID or metadata ID for the organization key. It is not the raw sk_orb_... secret.

​
Search one directory

Use searchScope.type: "directory" with the directory UUID:
curl
curl -X POST "https://api.orbitsearch.com/v2/developer/search" \
  -H "Authorization: Bearer $ORG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "founders in sf",
    "numUsers": 10,
    "searchScope": { "type": "directory", "directoryId": "DIRECTORY_UUID" }
  }'

​
Search multiple directories

Use searchScope.type: "directories" with an array of directory UUIDs. All directories must belong to the same organization. 
{
  "query": "founders in sf",
  "numUsers": 10,
  "searchScope": {
    "type": "directories",
    "directoryIds": ["DIRECTORY_UUID_A", "DIRECTORY_UUID_B"]
  }
}