API Reference — HireLens Docs

Documentation

Title Section Slug Order Published

# API Reference

Full programmatic access to HireLens hiring intelligence data.

---

## Authentication

All API requests require an API key in the `X-API-Key` header:

```
curl -H "X-API-Key: your_key_here" https://your-domain/api/v1/vacancies
```

Generate keys in [API Keys](/api/keys) (admin access required).

---

## Endpoints

### GET /api/v1/vacancies

List vacancies with filters and pagination.

**Query Parameters:**

| Param | Type | Description |
|-------|------|-------------|
| `page` | int | Page number (default: 1) |
| `per_page` | int | Results per page (default: 20, max: 100) |
| `role` | string | Filter by standardized role |
| `seniority` | string | Filter by experience level |
| `domain` | string | Filter by industry domain |
| `salary_min` | int | Minimum salary (USD) |
| `salary_max` | int | Maximum salary (USD) |
| `location_type` | string | remote / office / hybrid |
| `score_min` | float | Minimum AI quality score |
| `company` | string | Filter by company name |
| `days` | int | Only signals from last N days |
| `sort` | string | Sort order (created_desc, score_desc, salary_desc) |

**Response:**
```json
{
  "items": [
    {
      "id": 123,
      "title": "Senior Backend Engineer",
      "role": "Backend",
      "seniority": "Senior",
      "company_name": "ExampleCorp",
      "salary_min": 120000,
      "salary_max": 180000,
      "score": 8.5,
      "domains": ["DeFi", "Infrastructure"],
      "location_type": "remote",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1234,
  "page": 1,
  "pages": 62
}
```

### GET /api/v1/vacancies/:id

Get a single vacancy by ID with full analysis data.

### GET /api/v1/search

Semantic AI-powered search using vector embeddings.

| Param | Type | Description |
|-------|------|-------------|
| `q` | string | Natural language search query |
| `limit` | int | Max results (default: 20) |

### GET /api/v1/companies

List enriched company profiles with vacancy counts and metadata.

### GET /api/v1/stats

Platform-wide statistics: totals, averages, distributions.

---

## Rate Limits

| Tier | Limit | Use Case |
|------|-------|----------|
| **Free** | 100 requests/hour | Prototyping, testing |
| **Pro** | 1,000 requests/hour | Production integrations |
| **Enterprise** | Custom | High-volume pipelines |

Rate limit headers are included in every response:
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1704067200
```

---

## Error Codes

| Code | Meaning |
|------|---------|
| `401` | Missing or invalid API key |
| `403` | Rate limit exceeded |
| `404` | Resource not found |
| `422` | Invalid parameters |
| `500` | Internal server error |

All errors return JSON:
```json
{
  "detail": "Human-readable error message"
}
```

---

## Integration Examples

### Python
```python
import requests

headers = {"X-API-Key": "your_key"}
response = requests.get(
    "https://your-domain/api/v1/vacancies",
    headers=headers,
    params={"role": "backend", "seniority": "senior", "days": 30}
)
data = response.json()
```

### JavaScript
```javascript
const res = await fetch(
  'https://your-domain/api/v1/vacancies?role=backend&seniority=senior',
  { headers: { 'X-API-Key': 'your_key' } }
);
const data = await res.json();
```

### cURL
```bash
curl -H "X-API-Key: your_key" \
  "https://your-domain/api/v1/vacancies?domain=defi&score_min=7&days=30"
```

Documentation

New Article