Skip to main content

​
Authentication

All API endpoints require API key authentication using the X-API-Key header.

​
Getting Your API Key

  1. Log in to the Goldilocks web application
  2. Navigate to the API Keys section
  3. Create a new API key with the required scopes
  4. Copy the key (shown only once)
Never commit API keys to version control or share them publicly. Keep your API keys secure.

​
API Key Format

API keys are alphanumeric strings, typically 40+ characters long. Example: 0FPJsP2SzuKQy8JDel2UadDtWi1algmw1vIkteOC8sc

​
Using Your API Key

Include your API key in the X-API-Key header for all requests: 
curl -X POST https://api.goldilocksai.app/searches/query \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Find 20 software engineers in San Francisco"}'

​
API Key Scopes

API keys can have the following scopes:
  • searches:create - Execute new searches
  • searches:read - Retrieve search results
  • enrichment:read - Enrich profiles with additional data
  • jobs:read - Stream job progress via SSE

​
Rate Limiting

Rate limits are applied per API key:
  • POST /searches/query: 10 requests/minute, maximum 3 concurrent requests
  • POST /searches//more-profiles: 10 requests/minute, maximum 3 concurrent requests
  • POST /enrichment/profiles: 20 requests/minute
  • GET /searches//profiles: No rate limit
  • GET /jobs//stream: No rate limit
Rate limit information is included in response headers:
  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Requests remaining in current window
  • X-RateLimit-Reset - Unix timestamp when rate limit resets

​
Your First Request

  1. Get your API key (see above)
  2. Make a search request using the Searches endpoint
  3. Stream job progress using the Jobs endpoint to track your search
  4. Retrieve results once the job completes
  5. Enrich profiles with contact information using the Enrichment endpoint