Nyne Deep Research

Research any person using the Nyne Deep Research API. Submit an email, phone, social URL, or name and receive a comprehensive intelligence dossier with psych...

Security Scan

The skill's runtime instructions legitimately require API credentials and include potentially privacy-invasive behavior, but the registry metadata does not declare those required credentials and the instructions encourage behaviors (webhook callback URLs, storing secrets in shell files, showing full unredacted dossiers) that increase risk—this mismatch and scope creep warrant caution.

Purpose & Capability

The skill's stated purpose (performing deep person research via the Nyne API) aligns with the SKILL.md, which requires an API key and secret—those credentials are appropriate for the task. However, the registry metadata claims no required environment variables or primary credential, which is an incoherent/important mismatch.

Instruction Scope

Instructions explicitly require presenting full, untruncated dossiers (including sensitive psychographic and 'creepy-good' insights), poll and write responses to /tmp, and offer a 'callback_url' webhook option. The webhook option can send sensitive results to arbitrary external endpoints if used, and the 'show maximum depth' directive materially increases privacy/ethical risk by encouraging exposure of all collected data to the user or UI.

Install Mechanism

This is an instruction-only skill with no install spec and no code files, which minimizes install-time risk. It does rely on standard tools (curl, jq, python3) which is normal for a CLI-based API integration.

Credentials

The SKILL.md requires NYNE_API_KEY and NYNE_API_SECRET—proportionate to calling a private API—but the registry metadata does not list these required env vars (incoherent). The instructions also recommend persisting credentials in shell profile or a home .nyne_env file without guidance on file permissions, which can expose secrets. The callback_url parameter further enables exfiltration if misused.

Persistence & Privilege

The skill is not always-included and does not request elevated platform privileges. It does instruct storing secrets in user shell files (user-level persistence), but it does not modify other skills or system-wide settings.

Scan Findings in Context

[no_findings] expected: Scanner found no code files to analyze because this is an instruction-only skill. That is expected for a pure SKILL.md, but the SKILL.md itself declares NYNE_API_KEY and NYNE_API_SECRET while registry metadata shows no required env vars—this discrepancy is not something the regex scanner would catch.

What to consider before installing

This skill calls an external person-research API and its SKILL.md requires NYNE_API_KEY and NYNE_API_SECRET even though the registry metadata does not declare them—ask the publisher to fix the metadata before installing. Before using: verify the Nyne API provider is legitimate and that you have legal/ethical permission to research the target; avoid using callback_url to send results to third-party endpoints you don't control; do not store API secrets in world-readable files—use a secure secret store or at minimum restrict file permissions (chmod 600) and avoid echoing secrets into shell history; be aware the skill's instructions explicitly instruct showing full, unredacted dossiers (which may include highly sensitive personal data) and consider whether you need that level of detail. If you proceed, request that the registry entry be updated to list required env vars/primary credential and ask for clearer guidance on secure secret handling and safe defaults for webhook usage.

Nyne Deep Research Skill

Research any person by email, phone, social URL, or name. Returns a comprehensive intelligence dossier with psychographic profile, social graph, career analysis, conversation starters, and approach strategy.

Important: This API is async with high latency (2-5 min processing). You submit a request, get a request_id, then poll until complete.

Agent Instructions

When presenting results to the user, show maximum depth — display every section of the dossier in full. Do not summarize or truncate. Walk through each section sequentially:

1. Identity Snapshot — who they are
2. Career DNA — trajectory and superpower
3. Psychographic Profile — values, motivations, archetypes
4. Personal Life & Hobbies — interests outside work
5. Social Graph Analysis — inner circle, professional network, interest graph
6. Interest Cluster Deep Dive — all 9 clusters with detail
7. Content & Voice Analysis — topics, tone, opinions, quotes
8. Key Relationships — full list with relationship nature and importance
9. Conversation Starters — all 4 hook categories
10. Recommendations / How Others See Them — reputation signals
11. Warnings & Landmines — topics to avoid, sensitivities
12. Creepy-Good Insights — non-obvious findings with evidence
13. Approach Strategy — best angle, topics, what not to do

Also include enrichment data (contact info, work history, education) and note whether following and articles sections have data.

If dossier is null, present the enrichment data and let the user know the full dossier was not generated (this can happen with duplicate or cached requests — resubmit with a different identifier).

If following or articles are null, simply note they were not available for this person.

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.

Set these in your shell before running any commands:

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

To persist across sessions, add the exports to your shell profile (~/.zshrc, ~/.bashrc, etc.) or create a .env file and source it:

# 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

Verify they're set:

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 below use a nyne_parse helper that pipes through python3 to clean and re-encode the JSON before passing to jq. Define it once per session:

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

Submit a research request by email and poll until complete:

# 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": "[e-mail]"}' | 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

Submit Research (POST)

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

Headers:

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

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:

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": "[e-mail]"}' | nyne_parse | jq .

By social media URL:

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 '{"social_media_url": "https://twitter.com/elonmusk"}' | nyne_parse | jq .

By multiple social URLs:

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 '{"social_media_url": ["https://twitter.com/elonmusk", "https://linkedin.com/in/elonmusk"]}' | nyne_parse | jq .

By name + company:

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 '{"name": "Jane Smith", "company": "Acme Corp"}' | nyne_parse | jq .

By phone:

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 '{"phone": "[phone]"}' | nyne_parse | jq .

Submit response (HTTP 202):

{
  "success": true,
  "data": {
    "request_id": "abc123-def456-...",
    "status": "pending"
  }
}

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

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 | jq '{status: .data.status, completed: .data.completed}'

Full polling loop

SECONDS_WAITED=0
TIMEOUT=600  # 10 minutes

while [ $SECONDS_WAITED -lt $TIMEOUT ]; 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 "[$(date +%H:%M:%S)] Status: $STATUS ($SECONDS_WAITED s)"

  case "$STATUS" in
    completed)
      jq '.data.result' /tmp/nyne_response.json
      break
      ;;
    failed)
      echo "Research failed:"
      jq '.data' /tmp/nyne_response.json
      break
      ;;
    *)
      sleep 5
      SECONDS_WAITED=$((SECONDS_WAITED + 5))
      ;;
  esac
done

if [ "$STATUS" != "completed" ] && [ "$STATUS" != "failed" ]; then
  echo "Timed out. Resume polling with request_id: $REQUEST_ID"
fi

Response Structure

When status is completed, the response looks like:

{
  "success": true,
  "timestamp": "2025-01-15T12:00:00Z",
  "data": {
    "status": "completed",
    "completed": true,
    "request_id": "abc123-...",
    "created_on": "2025-01-15T11:57:00Z",
    "completed_on": "2025-01-15T12:00:00Z",
    "result": {
      "enrichment": { ... },
      "dossier": { ... },
      "following": { ... },
      "articles": [ ... ]
    }
  }
}

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:

# Extract identity snapshot
jq '.data.result.dossier.identity_snapshot' /tmp/nyne_response.json

# Get all conversation starters
jq '.data.result.dossier.conversation_starters' /tmp/nyne_response.json

# List key relationships (name + why important)
jq '.data.result.dossier.key_relationships[] | {name, why_important}' /tmp/nyne_response.json

# Get approach strategy
jq '.data.result.dossier.approach_strategy' /tmp/nyne_response.json

# Extract a specific dossier section by name
jq --arg s "psychographic_profile" '.data.result.dossier[$s]' /tmp/nyne_response.json

# Get enrichment contact info
jq '.data.result.enrichment | {emails, phones, linkedin_url, twitter_url}' /tmp/nyne_response.json

# Check processing status only
jq '{status: .data.status, completed: .data.completed, request_id: .data.request_id}' /tmp/nyne_response.json

# Get warnings and landmines
jq '.data.result.dossier.warnings_landmines' /tmp/nyne_response.json

# List all creepy-good insights
jq '.data.result.dossier.creepy_good_insights[].insight' /tmp/nyne_response.json

Error Handling

HTTP Code	Error	Description
400	INVALID_PARAMETERS	Malformed request body
400	MISSING_PARAMETER	No identifier provided (need email, phone, social_media_url, or name+company/city)
401	AUTHENTICATION_FAILED	Invalid or missing API key/secret
402	INSUFFICIENT_CREDITS	Not enough credits (100 credits per request)
403	NO_ACTIVE_SUBSCRIPTION	Subscription required
403	ACCESS_DENIED	Account does not have access
429	RATE_LIMIT_EXCEEDED	Too many requests
500	QUEUE_ERROR	Internal processing error

Rate Limits & Costs

• Rate limits: 10 requests/minute, 100 requests/hour
• Cost: 100 credits per research request
• Processing time: Typically 2-3 minutes, up to 5 minutes