# HeroHunt People Search API

> Enterprise-grade people search and enrichment API. Search for talent profiles across GitHub, StackOverflow, and the web using natural language queries.

## Getting Started

Sign up at https://www.herohunt.ai/app/api/sign-up to get your API key.
API documentation: https://www.herohunt.ai/people-search-api

## Python SDK

Official typed Python SDK. Install with `pip install herohunt`.

```python
from herohunt import HeroHunt

client = HeroHunt()  # reads HEROHUNT_API_KEY from env

result = client.people_search.search(
    "Senior React engineers in Berlin with TypeScript",
    max_results=50,
    enrich=True,
)
for profile in result.results:
    print(profile.first_name, profile.headline, profile.profile_url)
```

Sync (`HeroHunt`) and async (`AsyncHeroHunt`) clients share the same surface.
Typed errors: `AuthenticationError`, `InsufficientCreditsError`, `RateLimitError`, `BadRequestError`, `ServerError`.
PyPI: https://pypi.org/project/herohunt/
Source: https://github.com/herohunt-ai/herohunt-python

## MCP Server (Model Context Protocol)

HeroHunt exposes its People Search API as a hosted MCP server. Connect any MCP-compatible client (Claude Desktop, Cursor, ChatGPT Desktop, VS Code) in one step.

Endpoint: https://api.herohunt.ai/api/v1/mcp
Transport: Streamable HTTP (stateless)
Auth: Bearer token or x-api-key header

### Quick Setup (Claude Desktop / Cursor)

Add to your MCP config:
```json
{
  "mcpServers": {
    "herohunt-people-search": {
      "url": "https://api.herohunt.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Or install the npm package for stdio mode:
```
npx herohunt-mcp
```

## MCP Tools

### people_search - Search for people profiles
Natural language search across GitHub, StackOverflow, and the web.
Parameters: query (string), filters (object, optional), maxResults (number, 1-500, default 100), enrich (boolean), per_page (number, 1-50, default 10)
Credits: 1 credit per reserved slot up front (slots = min(maxResults, availableCredits)). Enrichment (enrich: true): +1 credit per LinkedIn profile returned with an email or phone.

### people_search_paginate - Paginate existing search
Fetch more results for a previously created search.
Parameters: searchId (string, required), page (number), per_page (number, 1-50), enrich (boolean)
Credits: Free (the maxResults reservation was billed on the creation call). With enrich: true, +1 credit per LinkedIn profile enriched on the page.

### account_usage_get - Get account usage
Returns plan, total/used/remaining credits, rate limit, and next credit reset date.
Parameters: none
Credits: Free

### account_searches_list - List past searches
Paginated history of past searches with first-page profiles.
Parameters: page (number), limit (number, max 100)
Credits: Free

### account_upgrade_link - Get upgrade URL
Returns a dashboard URL prefilled with account email for plan upgrades.
Parameters: none
Credits: Free

### account_billing_portal_link - Get billing portal URL
Returns Stripe Customer Portal URL for managing subscriptions and payment methods.
Parameters: none
Credits: Free

### api_keys_list - List API keys
Lists API key prefixes, scopes, and last-used timestamps.
Parameters: none
Credits: Free

### api_keys_create - Create API key
Create a new API key. Full key material is returned only once.
Parameters: name (string, required), scopes (array, optional), expiresAt (ISO-8601 datetime, optional)
Credits: Free

### api_keys_rotate - Rotate API key
Deactivate an existing key and issue a new one with the same scopes.
Parameters: keyId (string, required)
Credits: Free

### api_keys_revoke - Revoke API key
Permanently revoke an API key. Irreversible.
Parameters: keyId (string, required)
Credits: Free

## REST API

POST /api/v1/people-search/search - Search for people profiles
Auth: x-api-key header
Content-Type: application/json

Example:
```json
{
  "query": "Senior Java developers in Berlin with Spring Boot experience",
  "maxResults": 50,
  "enrich": true,
  "per_page": 10
}
```

## Pricing

Credits-based pricing. See https://www.herohunt.ai/app/api/dashboard for current plans.

## Contact

Email: info@herohunt.ai
Website: https://www.herohunt.ai
API Docs: https://www.herohunt.ai/people-search-api