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

# Authentication

> API key setup and tier limits

All API endpoints (except `/v1/health`) require an API key passed in the `X-API-Key` header.

## Getting a key

Sign up at [gildea.ai](https://gildea.ai) to receive your API key. Keys are prefixed with `gld_`.

## Using your key

Include the key in every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: gld_your_key_here" \
    "https://api.gildea.ai/v1/signals?keyword=test"
  ```

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

  headers = {"X-API-Key": "gld_your_key_here"}
  resp = requests.get("https://api.gildea.ai/v1/signals", headers=headers, params={"keyword": "test"})
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch("https://api.gildea.ai/v1/signals?keyword=test", {
    headers: { "X-API-Key": "gld_your_key_here" }
  });
  ```
</CodeGroup>

## Tiers

Every tier has access to all endpoints, including hybrid search. Tiers differ only in
request volume.

| Tier     | Rate limit | Monthly limit          |
| -------- | ---------- | ---------------------- |
| **Free** | 20 req/min | 250/month              |
| **Pro**  | 60 req/min | 5,000/month            |
| **Team** | Custom     | Custom (contact sales) |

## Error responses

An invalid, revoked, or expired API key returns `401`:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
}
```

If the `X-API-Key` header is omitted entirely, the API returns `422` (missing required header). If the header is present but the key is invalid, the API returns `401`.

## Security

* Keys are hashed with SHA-256 before storage; we never store plaintext keys
* Need a key rotated or revoked? Contact us and we'll revoke it immediately
* All requests are logged for usage tracking