API Reference

The Hadef AI public API lets you run the research pipeline, retrieve pitches, and send outreach programmatically. All endpoints are under /v1/ and require an API key.

Base URL: https://hadef.io · All endpoints accept and return JSON.

Authentication

Create API keys from Settings → API keys. Pass the key as a Bearer token:

Authorization: Bearer hdk_your_api_key_here

Keys are user-scoped. A revoked key is rejected immediately. The full key is shown once at creation, so store it securely.

Rate limits

Tier	Limit	Window
All API key requests	100 requests	Per hour
Pipeline runs	10 runs	Per hour

Exceeding the limit returns 429 Too Many Requests.

Error format

All errors return JSON with an error field:

{"error": "Invalid or missing API key", "hint": "Authorization: Bearer hdk_..."}

Pipeline

POST /v1/pipeline/run

Kick off a research pipeline run for a prospect. Returns immediately with a prospect_id to poll.

Request body

Field	Type	Description
`linkedin_url` required	string	Full LinkedIn profile URL
`prospect_name`	string	Full name (optional, improves research accuracy)

curl -X POST https://hadef.io/v1/pipeline/run \
  -H "Authorization: Bearer hdk_..." \
  -H "Content-Type: application/json" \
  -d '{"linkedin_url":"https://linkedin.com/in/example","prospect_name":"Jane Smith"}'

Response

{"prospect_id": "uuid", "status": "queued", "linkedin_url": "..."}

GET /v1/pipeline/{prospect_id}

Poll pipeline status. When status is qa_passed, the pitch field is populated.

curl https://hadef.io/v1/pipeline/uuid \
  -H "Authorization: Bearer hdk_..."

Response

{
  "prospect_id": "uuid",
  "status": "qa_passed",
  "updated_at": "2026-04-26T09:00:00Z",
  "pitch": {
    "pitch_id": "uuid",
    "linkedin_message": "...",
    "email_subject": "...",
    "email_body": "..."
  }
}

Pitch

POST /v1/pitch/send

Mark a pitch as sent and record the channel. Decrements credits.

Field	Type	Description
`pitch_id` required	string	UUID from pipeline response
`channel`	string	`linkedin` (default) or `email`

curl -X POST https://hadef.io/v1/pitch/send \
  -H "Authorization: Bearer hdk_..." \
  -H "Content-Type: application/json" \
  -d '{"pitch_id":"uuid","channel":"linkedin"}'

Response

{"sent_at": "2026-04-26T09:01:00Z", "channel": "linkedin"}

Prospects

GET /v1/prospects

List your prospects. Paginated, newest first.

Query param	Default	Description
`limit`	20	Max 100
`offset`	0	Pagination offset

curl "https://hadef.io/v1/prospects?limit=10&offset=0" \
  -H "Authorization: Bearer hdk_..."

Credits

GET /v1/credits

Check remaining credits and plan tier.

curl https://hadef.io/v1/credits \
  -H "Authorization: Bearer hdk_..."

Response

{"remaining": 47, "plan": "pro"}

Zapier integration

Use the Webhooks by Zapier action to call Hadef from any Zap:

Add a Webhooks by Zapier step, choose POST
URL: https://hadef.io/v1/pipeline/run
Headers: Authorization: Bearer hdk_your_key
Data: {"linkedin_url": "{{LinkedIn URL field}}"}
Add a second step to poll /v1/pipeline/{{prospect_id}} until status == qa_passed

curl examples

Full pipeline in bash

KEY="hdk_your_key_here"

# Start pipeline
PROSPECT=$(curl -s -X POST https://hadef.io/v1/pipeline/run \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedin_url":"https://linkedin.com/in/example"}')

ID=$(echo $PROSPECT | python3 -c "import sys,json; print(json.load(sys.stdin)['prospect_id'])")
echo "Pipeline started: $ID"

# Poll until done
while true; do
  STATUS=$(curl -s https://hadef.io/v1/pipeline/$ID \
    -H "Authorization: Bearer $KEY")
  S=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  echo "Status: $S"
  [ "$S" = "qa_passed" ] && break
  sleep 30
done

# Print pitch
echo $STATUS | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['pitch']['linkedin_message'])"

Hadef API v1 · Manage keys