> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goldilocksai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the Goldilocks AI Developer API

## 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](https://www.goldilocksai.co.uk)
2. Navigate to the API Keys section
3. Create a new API key with the required scopes
4. Copy the key (shown only once)

<Warning>
  Never commit API keys to version control or share them publicly. Keep your API keys secure.
</Warning>

### 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:

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://api.goldilocksai.app/searches/query",
      headers=headers,
      json={"query": "Find 20 software engineers in San Francisco"}
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.goldilocksai.app/searches/query', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: 'Find 20 software engineers in San Francisco'
    })
  });
  ```
</CodeGroup>

### 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/{search_id}/more-profiles**: 10 requests/minute, maximum 3 concurrent requests
* **POST /enrichment/profiles**: 20 requests/minute
* **GET /searches/{search_id}/profiles**: No rate limit
* **GET /jobs/{job_id}/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](/api-reference/searches)
3. **Stream job progress** using the [Jobs endpoint](/api-reference/jobs) to track your search
4. **Retrieve results** once the job completes
5. **Enrich profiles** with contact information using the [Enrichment endpoint](/api-reference/enrichment)