Update API docs with tier system and rate limit details

Author: 0xleal

docs/api-keys.mdx

@@ -8,8 +8,8 @@ description: Manage your Talent API keys.
 
 # API Keys
 
-API Keys are available exclusively for Talent+ members (5k requests/month).
+API Keys are available for Talent+ members. After getting your Talent+ membership on [talent.app](https://talent.app), you can request an API Key [here](https://talent.app/~/settings/api).
 
-After getting your Talent+ membership on [talent.app](https://talent.app), you can request an API Key [here](https://talent.app/~/settings/api).
+New API keys are created with the **free** tier by default (5,000 requests/month). For unlimited access, contact us to upgrade to **enterprise**.
 
 

docs/talent-api/authentication.mdx

@@ -10,7 +10,16 @@ The API key is the entry point for the Talent API. In order to perform requests
 
 We use the header `X-API-KEY` to retrieve the access key and validate your access to our API.
 
-There're two types of API keys:
+There are two types of API key permissions:
 
 - `read_only`: Can only access GET requests
 - `write`: Can access all requests
+
+### Tiers
+
+API keys are assigned one of two tiers:
+
+- **Free**: Default tier. Limited to 5,000 requests/month.
+- **Enterprise**: Unlimited requests.
+
+See [Rate Limits](/docs/talent-api/rate-limits) for details on usage tracking and headers.

docs/talent-api/rate-limits.mdx

@@ -3,9 +3,53 @@
 
 # Rate Limits
 
-## Rate Limits
+## Tiers
 
-Talent API usage is limited to 5,000 requests/month.
+API keys have two tiers with different usage limits:
+
+| Tier | Monthly Limit | Description |
+|------|--------------|-------------|
+| **Free** | 5,000 requests | Default tier for all new API keys |
+| **Enterprise** | Unlimited | Unlimited access |
+
+- Once the limit is reached, the API will block further requests with a `401` response.
+- Usage counters reset automatically at the beginning of each month.
+
+## Usage Headers
+
+Every successful response for **free tier** API keys includes the following headers:
+
+| Header | Description |
+|--------|-------------|
+| `X-API-Usage-Current` | Number of requests made in the current month |
+| `X-API-Usage-Limit` | Monthly request limit (5,000) |
+| `X-API-Usage-Status` | Current status: `ok`, `warning`, or `exceeded` |
+
+Enterprise tier keys do not receive these headers.
+
+## Usage Endpoint
+
+You can check your API key's usage details at any time, even if your key has exceeded the limit:
+
+```
+GET /api_keys/usage
+```
+
+Pass your API key via the `X-API-KEY` header. The response includes:
+
+```json
+{
+  "api_key_id": "uuid",
+  "tier": "free",
+  "current_usage": 150,
+  "limit": 5000,
+  "usage_status": "ok",
+  "period": "2026-02",
+  "resets_at": "2026-03-01T00:00:00Z"
+}
+```
+
+For enterprise keys, `current_usage` and `limit` will be `null`, and `usage_status` will be `unlimited`.
 
 ## Fair Use Policy