Developer reference

People Search API Reference

Search and enrich talent profiles across LinkedIn, GitHub, and Stack Overflow with one natural-language call. The same API powers the in-app dashboard, the official SDKs, and the hosted MCP server.

Base URLhttps://api.herohunt.ai/api/v1/people-search·Authenticate withx-api-key
Get API accessPython SDK
Getting started

Authentication

Every request authenticates with an API key. Create one from the dashboard, then send it as an x-api-key header (or Authorization: Bearer). Keys are prefixed ps_live_… and are shown only once.

x-api-key: YOUR_API_KEY

New to the API? Sign up for a key. The free trial includes 50 credits at 5 requests/min.

Plans: Trial (50 credits, 5/min) · HeroHunt API Starter (1400 credits, 15/min) · HeroHunt API Pro (3500 credits, 30/min).

Install

Official SDKs

Use the typed Python SDK, the Node / MCP package, or call the REST endpoints directly.

pip install herohunt

# then
from herohunt import HeroHunt
client = HeroHunt()  # reads HEROHUNT_API_KEY
result = client.people_search.search(
    "Senior React engineers in Berlin with TypeScript",
    max_results=50,
    enrich=True,
)
npx -y herohunt-mcp

# or point any MCP client at the hosted server:
# https://api.herohunt.ai/api/v1/mcp

People Search

Account

GET/account/usage

Get account usage

Returns current account plan, credits, and rate limit configuration.

Authenticationx-api-key header

Plans: Trial (50 credits, 5 req/min), HeroHunt API Starter (1400 credits, 15 req/min), HeroHunt API Pro (3500 credits, 30 req/min).

curl 'https://api.herohunt.ai/api/v1/people-search/account/usage' \
  -H 'x-api-key: YOUR_API_KEY'
{
  "plan": "trial",
  "creditsTotal": 50,
  "creditsUsed": 5,
  "creditsRemaining": 45,
  "creditResetDate": null,
  "rateLimit": 5
}
GET/account/keys

List API keys

List all API keys for this account. Returns prefixes only — full keys are never stored.

Authenticationx-api-key header
curl 'https://api.herohunt.ai/api/v1/people-search/account/keys' \
  -H 'x-api-key: YOUR_API_KEY'
[
  {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "keyPrefix": "ps_live_xxxx",
    "name": "Production Key",
    "scopes": ["people:search", "people:search:enrich"],
    "isActive": true,
    "expiresAt": null,
    "lastUsedAt": "2025-06-01T12:00:00.000Z",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
]
POST/account/keys

Create a new API key

Create a new API key. The raw key is returned only once — store it securely.

Authenticationx-api-key header
namestringrequired

A friendly name for this key.

scopesstring[]optional

Permission scopes: "people:search", "people:search:enrich". Defaults to ["people:search"].

expiresAtstringoptional

Expiration date (ISO 8601).

curl -X POST 'https://api.herohunt.ai/api/v1/people-search/account/keys' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{ "name": "Production Key" }'
{
  "apiKey": "ps_live_a1b2c3d4e5f6...",
  "keyPrefix": "ps_live_a1b2",
  "name": "Production Key",
  "scopes": ["people:search", "people:search:enrich"]
}
DELETE/account/keys/{keyId}

Revoke an API key

Permanently revoke an API key. Takes effect immediately.

Authenticationx-api-key header
curl -X DELETE 'https://api.herohunt.ai/api/v1/people-search/account/keys/KEY_ID' \
  -H 'x-api-key: YOUR_API_KEY'
POST/account/keys/{keyId}/rotate

Rotate an API key

Deactivates the existing key and creates a new one. The new key is returned only once.

Authenticationx-api-key header
curl -X POST 'https://api.herohunt.ai/api/v1/people-search/account/keys/KEY_ID/rotate' \
  -H 'x-api-key: YOUR_API_KEY'
{
  "apiKey": "ps_live_n3w4k3y5...",
  "keyPrefix": "ps_live_n3w4",
  "name": "Production Key",
  "scopes": ["people:search", "people:search:enrich"]
}
Agents

MCP server

The People Search API is also a hosted Model Context Protocol server. Point Claude, Cursor, or any MCP client at https://api.herohunt.ai/api/v1/mcp and authenticate with the same API key. Credits, rate limits, and scopes are shared across REST and MCP.

Connect in Claude Desktop
{
  "mcpServers": {
    "herohunt-people-search": {
      "url": "https://api.herohunt.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
Connect in Cursor
{
  "mcpServers": {
    "herohunt-people-search": {
      "url": "https://api.herohunt.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
Use from a custom agent (Node.js)
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api.herohunt.ai/api/v1/mcp"),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${process.env.HEROHUNT_API_KEY}` },
    },
  },
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const tools = await client.listTools();
const result = await client.callTool({
  name: "people_search",
  arguments: {
    query: "Senior Java developers in the US",
    maxResults: 50,
    per_page: 10,
  },
});
Raw HTTP / curl
# Raw HTTP / curl — useful for debugging only.
# Real MCP clients (Cursor, Claude Desktop, etc.) handle these headers automatically.
curl -X POST https://api.herohunt.ai/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

How search works (async pattern)

Searches run in the background, so people_search can return status: "processing" with zero or partial results. Follow the nextAction hint and poll the same searchId (pagination is free) until status === "completed".

{
  "searchId": "abc123",
  "status": "processing",
  "totalResults": 0,
  "pagination": { "page": 1, "per_page": 10, "has_more": false },
  "nextAction": {
    "tool": "people_search_paginate",
    "reason": "Search is still running. Poll the same searchId.",
    "arguments": { "searchId": "abc123", "page": 1, "per_page": 10 },
    "waitMs": 10000,
    "stopWhen": "status === \"completed\" || pagination.has_more === false"
  }
}

Available tools

ToolTypeSummary
people_searchWriteRun a new natural-language people search. Charges 1 credit per reserved slot up front.
people_search_paginateRead-onlyFetch additional pages for an existing searchId. Free unless enrich is enabled.
account_usage_getRead-onlyPlan, credits used / remaining, rate limit, next reset date.
account_searches_listRead-onlyPaginated history of past searches with first-page profiles.
account_upgrade_linkRead-onlyReturns a dashboard URL prefilled with your email, surface this on INSUFFICIENT_CREDITS.
account_billing_portal_linkRead-onlyStripe Customer Portal URL for managing or cancelling the subscription.
api_keys_listRead-onlyLists API key prefixes, scopes, last-used timestamps.
api_keys_createDestructiveCreate a new API key. Full key returned only once.
api_keys_rotateDestructiveDeactivate an existing key and return a new one with the same scopes.
api_keys_revokeDestructivePermanently revoke an API key.

Resources & prompts

  • herohunt://people-search/usage — JSON snapshot of credits & rate limit
  • herohunt://people-search/searches — recent search history
  • herohunt://people-search/searches/{searchId} — a single past search
  • Prompt templates find-candidates and enrich-page compose recruiter-grade queries.

Start building with the People Search API

Create an API key, install the SDK, and fetch real-time profiles from 1 billion candidates today.

Get API accessProduct overview