export NYNE_API_KEY="your-api-key"
export NYNE_API_SECRET="your-api-secret"

# Create .env file (keep out of version control)
echo 'export NYNE_API_KEY="your-api-key"' >> ~/.nyne_env
echo 'export NYNE_API_SECRET="your-api-secret"' >> ~/.nyne_env
source ~/.nyne_env

## Quick Start

Submit a research request by email and poll until complete:

## Submit Research (POST)

**Endpoint:** `POST https://api.nyne.ai/person/deep-research`

**Headers:**

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `email` | string | Email address |
| `phone` | string | Phone number |
| `social_media_url` | string or array | Social profile URL(s), up to 3 |
| `name` | string | Full name (use with `company` or `city` for disambiguation) |
| `company` | string | Company name (helps disambiguate `name`) |
| `city` | string | City (helps disambiguate `name`) |
| `callback_url` | string | Webhook URL to POST results when complete |

At least one identifier is required: `email`, `phone`, `social_media_url`, or `name` with `company`/`city`.

### Examples

**By email:**

## Poll for Results (GET)

**Endpoint:** `GET https://api.nyne.ai/person/deep-research?request_id={id}`

**Headers:** Same `X-API-Key` and `X-API-Secret` as above.

**Status progression:** `pending` → `enriching` → `gathering` → `analyzing` → `completed` (or `failed`)

This typically takes 2-3 minutes.

### Check status once

## Response Structure

When `status` is `completed`, the response looks like:

### `result` sections

| Section | Description |
|---------|-------------|
| `enrichment` | Contact info, social profiles, bio, schools, work history (20+ keys) |
| `dossier` | The main intelligence output — 15 sections (see below) |
| `following` | Twitter/Instagram following data (can be null) |
| `articles` | Press and media mentions (can be null) |

## Dossier Sections Reference

The `dossier` object contains 15 sections:

### `identity_snapshot`
Top-level identity summary.
- `full_name`, `current_role`, `company`, `location`, `age_estimate`, `emails`, `social_profiles`, `headline`, `birthday`, `self_description`

### `career_dna`
Career trajectory and strengths.
- `trajectory`, `superpower`

### `psychographic_profile`
Values, motivations, and personality archetypes.
- `values`, `motivations`, `archetypes`, `political_leanings`, `cluster_analysis`

### `personal_life_hobbies`
Interests and personality outside of work.
- `life_outside_work`, `entertainment_culture`, `personal_passions`, `active_hobbies_sports`, `quirks_personality`

### `social_graph_analysis`
Network and relationship mapping.
- `inner_circle`, `professional_network`, `personal_interest_graph`

### `interest_cluster_deep_dive`
Deep analysis across 9 interest clusters.
- `tech`, `sports_fitness`, `music_entertainment`, `food_lifestyle`, `causes_politics`, `intellectual_interests`, `geographic_ties`, `personal_network`, `unexpected_surprising`

### `content_voice_analysis`
How they communicate and what they care about.
- `topics`, `tone`, `humor_style`, `strong_opinions`, `frustrations`, `notable_quotes`, `recent_wins`

### `content_analysis`
Alias of `content_voice_analysis` (kept for backward compatibility).

### `key_relationships`
List of ~25 objects describing important connections.
- Each: `name`, `handle`, `followers`, `relationship_nature`, `why_important`

### `key_influencers`
Alias of `key_relationships`.

### `conversation_starters`
Hooks to open conversation, in 4 categories.
- `professional_hooks`, `personal_interest_hooks`, `current_events_hooks`, `shared_experience_hooks`

### `recommendations_how_others_see_them`
Public perception and reputation signals.
- `highlighted_qualities`, `colleague_descriptions`, `patterns_in_praise`

### `warnings_landmines`
Topics and areas to avoid.
- `topics_to_avoid`, `political_hot_buttons`, `sensitive_career_history`, `competitors_they_dislike`

### `creepy_good_insights`
Non-obvious insights derived from data.
- List of objects: `insight`, `evidence`

### `approach_strategy`
How to approach this person.
- `best_angle`, `topics_that_resonate`, `personal_interests_to_reference`, `shared_connections`, `what_not_to_do`

## Useful jq Filters

After polling completes, the clean response is at `/tmp/nyne_response.json`. Use `jq` directly on the file:

nyne_parse() {
  python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}

# Define helper (strips control chars, re-encodes clean JSON)
nyne_parse() {
  python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}

# Submit research request
REQUEST_ID=$(curl -s -X POST "https://api.nyne.ai/person/deep-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "[email protected]"}' | nyne_parse | jq -r '.data.request_id')

echo "Request submitted: $REQUEST_ID"

# Poll until complete (checks every 5s, times out after 10 min)
SECONDS_WAITED=0
while [ $SECONDS_WAITED -lt 600 ]; do
  curl -s "https://api.nyne.ai/person/deep-research?request_id=$REQUEST_ID" \
    -H "X-API-Key: $NYNE_API_KEY" \
    -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_response.json
  STATUS=$(jq -r '.data.status' /tmp/nyne_response.json)
  echo "Status: $STATUS ($SECONDS_WAITED seconds elapsed)"
  if [ "$STATUS" = "completed" ]; then
    jq '.data.result' /tmp/nyne_response.json
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Research failed."
    jq . /tmp/nyne_response.json
    break
  fi
  sleep 5
  SECONDS_WAITED=$((SECONDS_WAITED + 5))
done

if [ $SECONDS_WAITED -ge 600 ]; then
  echo "Timed out after 10 minutes. Try polling manually with request_id: $REQUEST_ID"
fi