nyne-search

What this skill does

# Nyne Search Skill

Search for people using natural language queries. Find professionals by role, company, location, industry, or any combination. Returns matching profiles with contact info, work history, education, and optional AI relevance scoring.

**Important:** This API is async. You POST to submit, get a `request_id`, then poll GET until `status: "completed"`. Light searches complete in 3-40 seconds; premium searches take 30-300 seconds.

## Agent Instructions

When presenting search results to the user, show **all returned data** for each person. Walk through:

1. **Result count** — total_stored, total_estimate, has_more, credits_charged
2. **Each person** — displayname, headline, bio, location, gender, estimated_age, total_experience_years, is_decision_maker
3. **Contact info** — best_business_email, best_personal_email, altemails, fullphone (if show_emails/show_phone_numbers were enabled)
4. **Social profiles** — LinkedIn URL, username, connections, followers
5. **Work history** — all organizations with title, dates, company details (industries, num_employees, funding, technologies)
6. **Education** — schools with degree, major, dates; note is_top_universities flag
7. **Interests** — work interests and certifications
8. **Patents** — title, date, reference, URL (if present)
9. **Languages** — spoken languages
10. **Score** — AI relevance score 0-1 (if profile_scoring was enabled)
11. **Insights** — AI-generated match reasoning (if insights were enabled)

If `has_more` is true, tell the user there are more results available and offer to paginate using the `next_cursor`.

If a field is missing from the response, it means no data was found — skip it silently.

## Setup

**Required environment variables:**
- `NYNE_API_KEY` — your Nyne API key
- `NYNE_API_SECRET` — your Nyne API secret

Get credentials at [https://api.nyne.ai](https://api.nyne.ai).

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

Verify they're set:
```bash
echo "Key: ${NYNE_API_KEY:0:8}... Secret: ${NYNE_API_SECRET:0:6}..."
```

## Important: JSON Handling

The API response can contain control characters in JSON string values that break `jq`. All examples use a `nyne_parse` helper that cleans and re-encodes JSON via `python3`. Define it once per session:

```bash
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)
"
}
```

## Quick Start

Search for people by natural language query and poll until complete:

```bash
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 search request
curl -s -X POST "https://api.nyne.ai/person/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"query": "Software engineers at Google in San Francisco", "limit": 10, "type": "premium", "show_emails": true}' | nyne_parse > /tmp/nyne_search.json

STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)

if [ "$STATUS" = "completed" ]; then
  echo "Search completed immediately."
  jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json
  jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
else
  REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_search.json)
  echo "Request submitted: $REQUEST_ID (status: $STATUS)"

  # 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/search?request_id=$REQUEST_ID" \
      -H "X-API-Key: $NYNE_API_KEY" \
      -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_search.json
    STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)
    echo "Status: $STATUS ($SECONDS_WAITED seconds elapsed)"
    if [ "$STATUS" = "completed" ]; then
      jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json
      jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
      break
    elif [ "$STATUS" = "failed" ]; then
      echo "Search failed."
      jq . /tmp/nyne_search.json
      break
    fi
    sleep 5
    SECONDS_WAITED=$((SECONDS_WAITED + 5))
  done

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

## Submit Search (POST)

**Endpoint:** `POST https://api.nyne.ai/person/search`

**Headers:**
```
Content-Type: application/json
X-API-Key: $NYNE_API_KEY
X-API-Secret: $NYNE_API_SECRET
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | *required* | Natural language search query (max 1000 chars). Examples: "Software engineers at Microsoft in Seattle", "Marketing directors at Fortune 500" |
| `type` | string | `"premium"` | Search quality tier: `"light"` (fast, 3-40s), `"medium"` (balanced), `"premium"` (best quality, 30-300s) |
| `limit` | integer | 10 | Results per request (max 100) |
| `offset` | integer | 0 | Starting position, 0-indexed (max 999). `offset + limit` must be ≤ 1000 |
| `show_emails` | boolean | false | Include email addresses in results (+2 credits). **Significantly increases latency** — search will take longer to complete as emails are enriched per result |
| `show_phone_numbers` | boolean | false | Include phone numbers in results (+14 credits). **Significantly increases latency** — search will take longer to complete as phone numbers are enriched per result |
| `require_emails` | boolean | false | Only return profiles that have email addresses (+1 credit) |
| `require_phone_numbers` | boolean | false | Only return profiles that have phone numbers (+1 credit) |
| `require_phones_or_emails` | boolean | false | Only return profiles with either phone or email (+1 credit) |
| `insights` | boolean | false | AI-generated insights per result explaining match relevance (+1 credit per result). Not available for `light` type |
| `profile_scoring` | boolean | false | Include AI relevance score (0-1) per result (+1 credit) |
| `high_freshness` | boolean | false | Prioritize recently updated profiles (+2 credits). Not available for `light` type |
| `force_new` | boolean | false | Force fresh search, ignore cached results |
| `custom_filters` | object | omit | Structured filters for precise targeting (see Custom Filters below) |
| `callback_url` | string | omit | Webhook URL for async results delivery |

### Custom Filters

Pass as a `custom_filters` object to narrow results beyond the natural language query.

**Array fields** (pass as arrays of strings):

| Filter | Description |
|--------|-------------|
| `locations` | Geographic locations (e.g., `["San Francisco", "New York"]`) |
| `languages` | Languages spoken (e.g., `["English", "Spanish"]`) |
| `titles` | Job titles (e.g., `["CTO", "VP Engineering"]`) |
| `industries` | Industry sectors (e.g., `["Technology", "Healthcare"]`) |
| `companies` | Company names, current or past (e.g., `["Google", "Meta"]`) |
| `universities` | Universities attended (e.g., `["Stanford", "MIT"]`) |
| `keywords` | Profile keywords (e.g., `["machine learning", "AI"]`) |
| `degrees` | Education degrees (e.g., `["bachelor", "master", "phd"]`) |
| `specialization_categories` | Academic specialization categories |

**Numeric range fields** (pass as integers):

| Filter | Description |
|--------|-------------|
| `min_linkedin_followers` / `max_linkedin_followers` | LinkedIn follower count range |
| `min_total_experience_years` / `max_total_experience_years` | Total work experience range |
| `min_current_experience_years` / `max_current_experience_years` | Current role tenure range |
| `min_estimated_age` / `max_estimated_age` | Estimated age range |

**Exact match fields**:

| Filter |