{
  "schemaVersion": "1.0",
  "item": {
    "slug": "nyne-search",
    "name": "Nyne Search",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/MichaelFanous2/nyne-search",
    "canonicalUrl": "https://clawhub.ai/MichaelFanous2/nyne-search",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/nyne-search",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=nyne-search",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/nyne-search"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/nyne-search",
    "agentPageUrl": "https://openagent3.xyz/skills/nyne-search/agent",
    "manifestUrl": "https://openagent3.xyz/skills/nyne-search/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/nyne-search/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Nyne Search Skill",
        "body": "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.\n\nImportant: 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."
      },
      {
        "title": "Agent Instructions",
        "body": "When presenting search results to the user, show all returned data for each person. Walk through:\n\nResult count — total_stored, total_estimate, has_more, credits_charged\nEach person — displayname, headline, bio, location, gender, estimated_age, total_experience_years, is_decision_maker\nContact info — best_business_email, best_personal_email, altemails, fullphone (if show_emails/show_phone_numbers were enabled)\nSocial profiles — LinkedIn URL, username, connections, followers\nWork history — all organizations with title, dates, company details (industries, num_employees, funding, technologies)\nEducation — schools with degree, major, dates; note is_top_universities flag\nInterests — work interests and certifications\nPatents — title, date, reference, URL (if present)\nLanguages — spoken languages\nScore — AI relevance score 0-1 (if profile_scoring was enabled)\nInsights — AI-generated match reasoning (if insights were enabled)\n\nIf has_more is true, tell the user there are more results available and offer to paginate using the next_cursor.\n\nIf a field is missing from the response, it means no data was found — skip it silently."
      },
      {
        "title": "Setup",
        "body": "Required environment variables:\n\nNYNE_API_KEY — your Nyne API key\nNYNE_API_SECRET — your Nyne API secret\n\nGet credentials at https://api.nyne.ai.\n\nexport NYNE_API_KEY=\"your-api-key\"\nexport NYNE_API_SECRET=\"your-api-secret\"\n\nVerify they're set:\n\necho \"Key: ${NYNE_API_KEY:0:8}... Secret: ${NYNE_API_SECRET:0:6}...\""
      },
      {
        "title": "Important: JSON Handling",
        "body": "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:\n\nnyne_parse() {\n  python3 -c \"\nimport sys, json, re\nraw = sys.stdin.read()\nclean = re.sub(r'[\\x00-\\x1f]+', ' ', raw)\ndata = json.loads(clean)\njson.dump(data, sys.stdout)\n\"\n}"
      },
      {
        "title": "Quick Start",
        "body": "Search for people by natural language query and poll until complete:\n\nnyne_parse() {\n  python3 -c \"\nimport sys, json, re\nraw = sys.stdin.read()\nclean = re.sub(r'[\\x00-\\x1f]+', ' ', raw)\ndata = json.loads(clean)\njson.dump(data, sys.stdout)\n\"\n}\n\n# Submit search request\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Software engineers at Google in San Francisco\", \"limit\": 10, \"type\": \"premium\", \"show_emails\": true}' | nyne_parse > /tmp/nyne_search.json\n\nSTATUS=$(jq -r '.data.status' /tmp/nyne_search.json)\n\nif [ \"$STATUS\" = \"completed\" ]; then\n  echo \"Search completed immediately.\"\n  jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json\n  jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\nelse\n  REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_search.json)\n  echo \"Request submitted: $REQUEST_ID (status: $STATUS)\"\n\n  # Poll until complete (checks every 5s, times out after 10 min)\n  SECONDS_WAITED=0\n  while [ $SECONDS_WAITED -lt 600 ]; do\n    curl -s \"https://api.nyne.ai/person/search?request_id=$REQUEST_ID\" \\\n      -H \"X-API-Key: $NYNE_API_KEY\" \\\n      -H \"X-API-Secret: $NYNE_API_SECRET\" | nyne_parse > /tmp/nyne_search.json\n    STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)\n    echo \"Status: $STATUS ($SECONDS_WAITED seconds elapsed)\"\n    if [ \"$STATUS\" = \"completed\" ]; then\n      jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json\n      jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n      break\n    elif [ \"$STATUS\" = \"failed\" ]; then\n      echo \"Search failed.\"\n      jq . /tmp/nyne_search.json\n      break\n    fi\n    sleep 5\n    SECONDS_WAITED=$((SECONDS_WAITED + 5))\n  done\n\n  if [ $SECONDS_WAITED -ge 600 ]; then\n    echo \"Timed out after 10 minutes. Resume polling with request_id: $REQUEST_ID\"\n  fi\nfi"
      },
      {
        "title": "Submit Search (POST)",
        "body": "Endpoint: POST https://api.nyne.ai/person/search\n\nHeaders:\n\nContent-Type: application/json\nX-API-Key: $NYNE_API_KEY\nX-API-Secret: $NYNE_API_SECRET"
      },
      {
        "title": "Query Parameters",
        "body": "ParameterTypeDefaultDescriptionquerystringrequiredNatural language search query (max 1000 chars). Examples: \"Software engineers at Microsoft in Seattle\", \"Marketing directors at Fortune 500\"typestring\"premium\"Search quality tier: \"light\" (fast, 3-40s), \"medium\" (balanced), \"premium\" (best quality, 30-300s)limitinteger10Results per request (max 100)offsetinteger0Starting position, 0-indexed (max 999). offset + limit must be ≤ 1000show_emailsbooleanfalseInclude email addresses in results (+2 credits). Significantly increases latency — search will take longer to complete as emails are enriched per resultshow_phone_numbersbooleanfalseInclude phone numbers in results (+14 credits). Significantly increases latency — search will take longer to complete as phone numbers are enriched per resultrequire_emailsbooleanfalseOnly return profiles that have email addresses (+1 credit)require_phone_numbersbooleanfalseOnly return profiles that have phone numbers (+1 credit)require_phones_or_emailsbooleanfalseOnly return profiles with either phone or email (+1 credit)insightsbooleanfalseAI-generated insights per result explaining match relevance (+1 credit per result). Not available for light typeprofile_scoringbooleanfalseInclude AI relevance score (0-1) per result (+1 credit)high_freshnessbooleanfalsePrioritize recently updated profiles (+2 credits). Not available for light typeforce_newbooleanfalseForce fresh search, ignore cached resultscustom_filtersobjectomitStructured filters for precise targeting (see Custom Filters below)callback_urlstringomitWebhook URL for async results delivery"
      },
      {
        "title": "Custom Filters",
        "body": "Pass as a custom_filters object to narrow results beyond the natural language query.\n\nArray fields (pass as arrays of strings):\n\nFilterDescriptionlocationsGeographic locations (e.g., [\"San Francisco\", \"New York\"])languagesLanguages spoken (e.g., [\"English\", \"Spanish\"])titlesJob titles (e.g., [\"CTO\", \"VP Engineering\"])industriesIndustry sectors (e.g., [\"Technology\", \"Healthcare\"])companiesCompany names, current or past (e.g., [\"Google\", \"Meta\"])universitiesUniversities attended (e.g., [\"Stanford\", \"MIT\"])keywordsProfile keywords (e.g., [\"machine learning\", \"AI\"])degreesEducation degrees (e.g., [\"bachelor\", \"master\", \"phd\"])specialization_categoriesAcademic specialization categories\n\nNumeric range fields (pass as integers):\n\nFilterDescriptionmin_linkedin_followers / max_linkedin_followersLinkedIn follower count rangemin_total_experience_years / max_total_experience_yearsTotal work experience rangemin_current_experience_years / max_current_experience_yearsCurrent role tenure rangemin_estimated_age / max_estimated_ageEstimated age range\n\nExact match fields:\n\nFilterTypeDescriptionfirst_namestringExact first name matchmiddle_namestringExact middle name matchlast_namestringExact last name matchgenderstring\"male\" or \"female\"studied_at_top_universitiesbooleanAttended a top-ranked university"
      },
      {
        "title": "Examples",
        "body": "Basic search:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Software engineers at Google in San Francisco\", \"limit\": 10}' | nyne_parse > /tmp/nyne_search.json\n\njq '{status: .data.status, request_id: .data.request_id}' /tmp/nyne_search.json\n\nWith emails and phone numbers:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Marketing directors at tech startups in Austin\", \"limit\": 25, \"show_emails\": true, \"show_phone_numbers\": true}' | nyne_parse > /tmp/nyne_search.json\n\nWith custom filters:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\n    \"query\": \"Engineering leaders in fintech\",\n    \"limit\": 20,\n    \"type\": \"premium\",\n    \"show_emails\": true,\n    \"custom_filters\": {\n      \"locations\": [\"New York\", \"San Francisco\"],\n      \"titles\": [\"CTO\", \"VP Engineering\", \"Head of Engineering\"],\n      \"min_total_experience_years\": 10,\n      \"industries\": [\"Financial Services\", \"Technology\"]\n    }\n  }' | nyne_parse > /tmp/nyne_search.json\n\nLight search (fast, 1 credit):\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Data scientists at Amazon\", \"type\": \"light\", \"limit\": 10}' | nyne_parse > /tmp/nyne_search.json\n\nWith AI scoring and insights:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"AI researchers in healthcare\", \"type\": \"premium\", \"profile_scoring\": true, \"insights\": true, \"limit\": 10}' | nyne_parse > /tmp/nyne_search.json\n\nWith freshness priority:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Product managers who recently changed jobs\", \"type\": \"premium\", \"high_freshness\": true, \"show_emails\": true}' | nyne_parse > /tmp/nyne_search.json\n\nRequire contact info:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Sales directors at SaaS companies\", \"require_emails\": true, \"show_emails\": true, \"limit\": 50}' | nyne_parse > /tmp/nyne_search.json\n\nSubmit response:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"request_id\": \"abc12345_1737123456_1234\",\n    \"status\": \"completed\",\n    \"results\": [...],\n    \"offset\": 0,\n    \"limit\": 10,\n    \"total_stored\": 47,\n    \"total_estimate\": 2500,\n    \"has_more\": true,\n    \"next_cursor\": \"eyJvIjoxMCwiciI6ImFiYzEyMzQ1XzE3MzcxMjM0NTZfMTIzNCJ9\",\n    \"from_cache\": false,\n    \"credits_charged\": 7\n  },\n  \"timestamp\": \"2026-02-19T...\"\n}\n\nNote: The POST may return status: \"completed\" immediately (especially for cached or light searches) or status: \"processing\" requiring polling. Always check the status."
      },
      {
        "title": "Poll for Results (GET)",
        "body": "Endpoint: GET https://api.nyne.ai/person/search?request_id={id}\n\nHeaders: Same X-API-Key and X-API-Secret as above."
      },
      {
        "title": "Check status once",
        "body": "curl -s \"https://api.nyne.ai/person/search?request_id=$REQUEST_ID\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" | nyne_parse > /tmp/nyne_search.json\n\njq '{status: .data.status, total_stored: .data.total_stored}' /tmp/nyne_search.json"
      },
      {
        "title": "Full polling loop",
        "body": "SECONDS_WAITED=0\nTIMEOUT=600  # 10 minutes\n\nwhile [ $SECONDS_WAITED -lt $TIMEOUT ]; do\n  curl -s \"https://api.nyne.ai/person/search?request_id=$REQUEST_ID\" \\\n    -H \"X-API-Key: $NYNE_API_KEY\" \\\n    -H \"X-API-Secret: $NYNE_API_SECRET\" | nyne_parse > /tmp/nyne_search.json\n  STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)\n\n  echo \"[$(date +%H:%M:%S)] Status: $STATUS ($SECONDS_WAITED s)\"\n\n  case \"$STATUS\" in\n    completed)\n      jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json\n      jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n      break\n      ;;\n    failed)\n      echo \"Search failed:\"\n      jq '.data' /tmp/nyne_search.json\n      break\n      ;;\n    *)\n      sleep 5\n      SECONDS_WAITED=$((SECONDS_WAITED + 5))\n      ;;\n  esac\ndone\n\nif [ \"$STATUS\" != \"completed\" ] && [ \"$STATUS\" != \"failed\" ]; then\n  echo \"Timed out. Resume polling with request_id: $REQUEST_ID\"\nfi"
      },
      {
        "title": "Pagination",
        "body": "After the initial search completes, paginate through results for free (cached results, no additional credits)."
      },
      {
        "title": "Cursor-based pagination (recommended)",
        "body": "Use the next_cursor from the previous response:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"cursor\": \"eyJvIjoxMCwiciI6ImFiYzEyMzQ1XzE3MzcxMjM0NTZfMTIzNCJ9\"}' | nyne_parse > /tmp/nyne_search.json\n\njq '.data | {total_stored, offset, limit, has_more}' /tmp/nyne_search.json\njq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json"
      },
      {
        "title": "Offset-based pagination",
        "body": "Use request_id + offset from the original search:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"request_id\": \"abc12345_1737123456_1234\", \"offset\": 25, \"limit\": 25}' | nyne_parse > /tmp/nyne_search.json\n\njq '.data | {total_stored, offset, limit, has_more}' /tmp/nyne_search.json\njq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n\nPagination notes:\n\nPaginating through cached results is free — no additional credits charged\nMaximum 1000 results per search (offset + limit ≤ 1000)\nhas_more indicates whether more results are available\nnext_cursor is only present when has_more is true\nResults are cached for 30 days"
      },
      {
        "title": "Response Structure",
        "body": "When status is completed:\n\n{\n  \"success\": true,\n  \"timestamp\": \"2026-02-19T...\",\n  \"data\": {\n    \"request_id\": \"abc12345_1737123456_1234\",\n    \"status\": \"completed\",\n    \"results\": [\n      {\n        \"displayname\": \"Jane Smith\",\n        \"headline\": \"Senior Software Engineer at Google\",\n        \"bio\": \"...\",\n        \"location\": \"San Francisco, CA\",\n        \"gender\": \"female\",\n        \"estimated_age\": 35,\n        \"total_experience_years\": 12,\n        \"is_decision_maker\": 1,\n        \"is_top_universities\": true,\n        \"languages\": [\"English\", \"Spanish\"],\n        \"interests\": {\n          \"work\": [\"software engineering\", \"machine learning\", \"distributed systems\"],\n          \"certification\": [\"AWS Solutions Architect\"]\n        },\n        \"patents\": [],\n        \"best_business_email\": \"jane@google.com\",\n        \"best_personal_email\": \"jane@gmail.com\",\n        \"altemails\": [\"j.smith@gmail.com\"],\n        \"fullphone\": [{\"fullphone\": \"+14155551234\", \"type\": \"mobile\"}],\n        \"social_profiles\": {\n          \"linkedin\": {\n            \"url\": \"https://www.linkedin.com/in/janesmith\",\n            \"username\": \"janesmith\",\n            \"connections\": 1243,\n            \"followers\": 542,\n            \"photo_url\": \"...\"\n          }\n        },\n        \"organizations\": [\n          {\n            \"name\": \"Google\",\n            \"title\": \"Senior Software Engineer\",\n            \"startDate\": \"3-2020\",\n            \"location\": \"San Francisco\",\n            \"company_website\": \"google.com\",\n            \"industries\": [\"Technology\"],\n            \"num_employees\": \"10001+\"\n          }\n        ],\n        \"schools_attended\": [\"Stanford University\"],\n        \"schools_info\": [\n          {\n            \"name\": \"Stanford University\",\n            \"degree\": \"Master's\",\n            \"title\": \"Computer Science\",\n            \"startDate\": \"2012\",\n            \"endDate\": \"2014\"\n          }\n        ],\n        \"score\": 0.92,\n        \"insights\": {\n          \"match_reasoning\": \"Strong match based on...\"\n        }\n      }\n    ],\n    \"offset\": 0,\n    \"limit\": 10,\n    \"total_stored\": 47,\n    \"total_estimate\": 2500,\n    \"has_more\": true,\n    \"next_cursor\": \"eyJvIjoxMCwi...\",\n    \"from_cache\": false,\n    \"credits_charged\": 7\n  }\n}"
      },
      {
        "title": "Result Fields",
        "body": "FieldTypeDescriptiondisplaynamestringPerson's full nameheadlinestringCurrent job title/headlinebiostringProfessional biographylocationstringGeographic locationgenderstring\"male\" or \"female\"estimated_ageintegerEstimated agetotal_experience_yearsintegerYears of total work experienceis_decision_makerintegerWhether person holds decision-making authority (1 = yes)is_top_universitiesbooleanWhether person attended a top-ranked universitylanguagesarrayLanguages spoken (array of strings)interestsobject{work: [...], certification: [...]} — work interests and certificationspatentsarrayPatents held: {title, description, date, reference, url}best_business_emailstringPrimary business email (requires show_emails: true)best_personal_emailstringPrimary personal email (requires show_emails: true)altemailsarrayAlternative email addresses (requires show_emails: true)fullphonearrayPhone numbers with type (requires show_phone_numbers: true). Each: {fullphone, type}social_profilesobjectSocial profile data (see below)organizationsarrayWork history (see below)schools_attendedarrayUniversity names as stringsschools_infoarrayDetailed education: {name, degree, major, startDate, endDate}scorenumberAI relevance score 0-1 (requires profile_scoring: true)insightsobjectAI-generated match reasoning (requires insights: true)"
      },
      {
        "title": "Social Profiles Object",
        "body": "{\n  \"linkedin\": {\n    \"url\": \"https://www.linkedin.com/in/...\",\n    \"username\": \"...\",\n    \"connections\": 1243,\n    \"followers\": 542,\n    \"photo_url\": \"...\"\n  }\n}"
      },
      {
        "title": "Organization Object",
        "body": "{\n  \"name\": \"Windfall Bio\",\n  \"title\": \"Vice President of Software Engineering\",\n  \"startDate\": \"2024-08-01\",\n  \"endDate\": null,\n  \"location\": \"San Mateo, California, United States\",\n  \"company_website\": \"http://www.windfall.bio\",\n  \"company_linkedin_url\": \"https://www.linkedin.com/company/windfallbio\",\n  \"company_domain\": \"windfall.bio\",\n  \"industries\": [\"Manufacturing\"],\n  \"num_employees\": 37,\n  \"num_employees_range\": \"11-50\",\n  \"is_startup\": true,\n  \"is_b2b\": true,\n  \"is_b2c\": false,\n  \"is_saas\": false,\n  \"founded_in\": 2022,\n  \"latest_funding_round\": \"Series A\",\n  \"latest_funding_amount\": 28000000,\n  \"funding_total_usd\": 37000000,\n  \"annual_revenue\": 345000,\n  \"specialties\": [\"methane\", \"climate\", \"agtech\"],\n  \"technologies\": [\"Google Analytics\", \"AWS Lambda\", \"Webflow\"],\n  \"companyDesc\": \"...\",\n  \"logo_url\": \"...\"\n}\n\nOrganizations include rich company intelligence: funding data, tech stack, employee counts, and B2B/B2C/SaaS flags. Not all fields are present for every organization."
      },
      {
        "title": "Response Metadata Fields",
        "body": "FieldTypeDescriptiontotal_storedintegerNumber of results stored from this searchtotal_estimateintegerEstimated total matching profileshas_morebooleanWhether more results are available for paginationnext_cursorstringOpaque pagination token for next page (present when has_more is true)from_cachebooleanWhether results came from cache (30-day TTL)credits_chargedintegerTotal credits charged for this requestoffsetintegerCurrent offset in result setlimitintegerResults per page"
      },
      {
        "title": "Useful jq Filters",
        "body": "After polling completes, the clean response is at /tmp/nyne_search.json:\n\n# Search metadata\njq '.data | {total_stored, total_estimate, has_more, credits_charged, from_cache}' /tmp/nyne_search.json\n\n# List all people (name + headline + location)\njq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n\n# All emails\njq '.data.results[] | {displayname, best_business_email, best_personal_email, altemails}' /tmp/nyne_search.json\n\n# Phone numbers\njq '.data.results[] | {displayname, fullphone}' /tmp/nyne_search.json\n\n# LinkedIn profiles\njq '.data.results[] | {displayname, linkedin: .social_profiles.linkedin.url}' /tmp/nyne_search.json\n\n# Work history per person\njq '.data.results[] | {displayname, orgs: [.organizations[] | {name, title}]}' /tmp/nyne_search.json\n\n# Decision makers only\njq '[.data.results[] | select(.is_decision_maker == true)] | length' /tmp/nyne_search.json\njq '[.data.results[] | select(.is_decision_maker == true) | {displayname, headline}]' /tmp/nyne_search.json\n\n# Sort by relevance score (if profile_scoring enabled)\njq '[.data.results | sort_by(-.score)[] | {displayname, headline, score}]' /tmp/nyne_search.json\n\n# Experience range\njq '.data.results[] | {displayname, total_experience_years} | select(.total_experience_years >= 10)' /tmp/nyne_search.json\n\n# Education\njq '.data.results[] | {displayname, schools: .schools_attended}' /tmp/nyne_search.json\n\n# Interests and certifications\njq '.data.results[] | {displayname, work_interests: .interests.work, certifications: .interests.certification}' /tmp/nyne_search.json\n\n# Patents\njq '.data.results[] | select(.patents | length > 0) | {displayname, patents: [.patents[] | {title, date}]}' /tmp/nyne_search.json\n\n# Company intelligence (funding, tech stack)\njq '.data.results[] | {displayname, companies: [.organizations[] | {name, funding_total_usd, latest_funding_round, num_employees, is_startup}]}' /tmp/nyne_search.json\n\n# Get next_cursor for pagination\njq -r '.data.next_cursor' /tmp/nyne_search.json\n\n# Count results\njq '.data.results | length' /tmp/nyne_search.json"
      },
      {
        "title": "Error Handling",
        "body": "HTTP CodeErrorDescription400invalid_parametersInvalid parameter value or missing query400invalid_custom_filtersMalformed custom_filters object401invalid_credentialsInvalid API key/secret404request_not_foundInvalid request_id for status check (GET only)429rate_limit_exceededToo many requests429insufficient_creditsNot enough credits for this search500internal_errorServer error"
      },
      {
        "title": "Fast Search — type: \"light\" (1 credit per result)",
        "body": "Basic search with fast results in 3-40 seconds. Best for quick lookups when you need a broad list of names and don't need deep profile data. AI features (insights, high_freshness) are NOT available for light type. Profile scoring is available.\n\n{\"query\": \"Software engineers at Google\", \"type\": \"light\", \"limit\": 50}"
      },
      {
        "title": "Smart Search — type: \"medium\"",
        "body": "Balanced tier between speed and quality. Use when you want better matching than light but don't need the full depth of premium. Supports all AI features.\n\n{\"query\": \"Engineering managers in fintech\", \"type\": \"medium\", \"limit\": 25}"
      },
      {
        "title": "Pro Search — type: \"premium\" (5 credits per result)",
        "body": "Comprehensive search taking 30-300 seconds. Best quality results with deepest profile matching. Required for maximum-quality insights and high_freshness results. Use when result quality matters more than speed.\n\n{\"query\": \"AI researchers at top universities\", \"type\": \"premium\", \"limit\": 10, \"insights\": true, \"profile_scoring\": true}"
      },
      {
        "title": "AI-Powered Analysis Features",
        "body": "These features add intelligence on top of search results. Insights and High Freshness are NOT available for light type searches — use medium or premium."
      },
      {
        "title": "Query Insights (insights: true, +1 credit per result)",
        "body": "AI-generated analysis for each result explaining why this person matches your search query. Returns structured reasoning about the match relevance — how their background, role, and experience align with what you're looking for. Invaluable for qualifying leads or evaluating candidates at scale. Use when you need to understand the \"why\" behind each match, not just the \"who\".\n\n{\"query\": \"AI researchers in healthcare\", \"type\": \"premium\", \"insights\": true, \"limit\": 10}"
      },
      {
        "title": "Profile Scoring (profile_scoring: true, +1 credit)",
        "body": "AI relevance scoring that assigns each result a score from 0 to 1, where 1.0 is a perfect match. Use to rank and prioritize results by relevance. Works with all search tiers including light. Combine with insights for both a score and an explanation.\n\n{\"query\": \"Senior engineers at fintech startups\", \"profile_scoring\": true, \"limit\": 25}"
      },
      {
        "title": "High Freshness (high_freshness: true, +2 credits)",
        "body": "Prioritizes profiles that have been recently updated — people who recently changed jobs, updated their LinkedIn, or have fresh activity. Use when recency matters: hiring recently active candidates, targeting people who just moved to a new role, or finding profiles with current contact info. Not available for light type.\n\n{\"query\": \"Product managers who recently changed jobs\", \"type\": \"premium\", \"high_freshness\": true, \"show_emails\": true}"
      },
      {
        "title": "Combining AI Features",
        "body": "Stack insights + scoring + freshness for maximum intelligence:\n\n{\n  \"query\": \"VP of Engineering at Series B startups in San Francisco\",\n  \"type\": \"premium\",\n  \"insights\": true,\n  \"profile_scoring\": true,\n  \"high_freshness\": true,\n  \"show_emails\": true,\n  \"limit\": 10\n}"
      },
      {
        "title": "Credit Costs",
        "body": "Credits are charged based on features used per request. Pagination within cached results is free.\n\nFeatureCreditsDescriptionFast Search (type: \"light\")1Basic search, fastest response (3-40 seconds)Pro Search (type: \"premium\")5Comprehensive search, best quality (30-300 seconds)Smart Ranking (profile_scoring, boolean)1AI-powered relevance scoring of resultsCandidate Insights (insights, boolean)1AI-generated insights about each resultRealtime Profiles (high_freshness, boolean)2Prioritize recently updated profilesFilter Without Contact Data1Search without email/phone enrichmentEnrich Phones (show_phone_numbers, boolean)14Include phone numbers in results. Significantly increases latencyEnrich Emails (show_emails, boolean)2Include email addresses in results. Significantly increases latencyRequire Emails (require_emails, boolean)1Only return profiles with email addressesRequire Phones (require_phone_numbers, boolean)1Only return profiles with phone numbersRequire Contact Info (require_phones_or_emails, boolean)1Only return profiles with phone OR emailPagination (cached)0Free after initial search (30-day cache)"
      },
      {
        "title": "Rate Limits",
        "body": "Per minute: 60 requests\nPer hour: 1,000 requests\nMonthly: Plan-dependent"
      }
    ],
    "body": "Nyne Search Skill\n\nSearch 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.\n\nImportant: 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.\n\nAgent Instructions\n\nWhen presenting search results to the user, show all returned data for each person. Walk through:\n\nResult count — total_stored, total_estimate, has_more, credits_charged\nEach person — displayname, headline, bio, location, gender, estimated_age, total_experience_years, is_decision_maker\nContact info — best_business_email, best_personal_email, altemails, fullphone (if show_emails/show_phone_numbers were enabled)\nSocial profiles — LinkedIn URL, username, connections, followers\nWork history — all organizations with title, dates, company details (industries, num_employees, funding, technologies)\nEducation — schools with degree, major, dates; note is_top_universities flag\nInterests — work interests and certifications\nPatents — title, date, reference, URL (if present)\nLanguages — spoken languages\nScore — AI relevance score 0-1 (if profile_scoring was enabled)\nInsights — AI-generated match reasoning (if insights were enabled)\n\nIf has_more is true, tell the user there are more results available and offer to paginate using the next_cursor.\n\nIf a field is missing from the response, it means no data was found — skip it silently.\n\nSetup\n\nRequired environment variables:\n\nNYNE_API_KEY — your Nyne API key\nNYNE_API_SECRET — your Nyne API secret\n\nGet credentials at https://api.nyne.ai.\n\nexport NYNE_API_KEY=\"your-api-key\"\nexport NYNE_API_SECRET=\"your-api-secret\"\n\n\nVerify they're set:\n\necho \"Key: ${NYNE_API_KEY:0:8}... Secret: ${NYNE_API_SECRET:0:6}...\"\n\nImportant: JSON Handling\n\nThe 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:\n\nnyne_parse() {\n  python3 -c \"\nimport sys, json, re\nraw = sys.stdin.read()\nclean = re.sub(r'[\\x00-\\x1f]+', ' ', raw)\ndata = json.loads(clean)\njson.dump(data, sys.stdout)\n\"\n}\n\nQuick Start\n\nSearch for people by natural language query and poll until complete:\n\nnyne_parse() {\n  python3 -c \"\nimport sys, json, re\nraw = sys.stdin.read()\nclean = re.sub(r'[\\x00-\\x1f]+', ' ', raw)\ndata = json.loads(clean)\njson.dump(data, sys.stdout)\n\"\n}\n\n# Submit search request\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Software engineers at Google in San Francisco\", \"limit\": 10, \"type\": \"premium\", \"show_emails\": true}' | nyne_parse > /tmp/nyne_search.json\n\nSTATUS=$(jq -r '.data.status' /tmp/nyne_search.json)\n\nif [ \"$STATUS\" = \"completed\" ]; then\n  echo \"Search completed immediately.\"\n  jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json\n  jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\nelse\n  REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_search.json)\n  echo \"Request submitted: $REQUEST_ID (status: $STATUS)\"\n\n  # Poll until complete (checks every 5s, times out after 10 min)\n  SECONDS_WAITED=0\n  while [ $SECONDS_WAITED -lt 600 ]; do\n    curl -s \"https://api.nyne.ai/person/search?request_id=$REQUEST_ID\" \\\n      -H \"X-API-Key: $NYNE_API_KEY\" \\\n      -H \"X-API-Secret: $NYNE_API_SECRET\" | nyne_parse > /tmp/nyne_search.json\n    STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)\n    echo \"Status: $STATUS ($SECONDS_WAITED seconds elapsed)\"\n    if [ \"$STATUS\" = \"completed\" ]; then\n      jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json\n      jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n      break\n    elif [ \"$STATUS\" = \"failed\" ]; then\n      echo \"Search failed.\"\n      jq . /tmp/nyne_search.json\n      break\n    fi\n    sleep 5\n    SECONDS_WAITED=$((SECONDS_WAITED + 5))\n  done\n\n  if [ $SECONDS_WAITED -ge 600 ]; then\n    echo \"Timed out after 10 minutes. Resume polling with request_id: $REQUEST_ID\"\n  fi\nfi\n\nSubmit Search (POST)\n\nEndpoint: POST https://api.nyne.ai/person/search\n\nHeaders:\n\nContent-Type: application/json\nX-API-Key: $NYNE_API_KEY\nX-API-Secret: $NYNE_API_SECRET\n\nQuery Parameters\nParameter\tType\tDefault\tDescription\nquery\tstring\trequired\tNatural language search query (max 1000 chars). Examples: \"Software engineers at Microsoft in Seattle\", \"Marketing directors at Fortune 500\"\ntype\tstring\t\"premium\"\tSearch quality tier: \"light\" (fast, 3-40s), \"medium\" (balanced), \"premium\" (best quality, 30-300s)\nlimit\tinteger\t10\tResults per request (max 100)\noffset\tinteger\t0\tStarting position, 0-indexed (max 999). offset + limit must be ≤ 1000\nshow_emails\tboolean\tfalse\tInclude email addresses in results (+2 credits). Significantly increases latency — search will take longer to complete as emails are enriched per result\nshow_phone_numbers\tboolean\tfalse\tInclude phone numbers in results (+14 credits). Significantly increases latency — search will take longer to complete as phone numbers are enriched per result\nrequire_emails\tboolean\tfalse\tOnly return profiles that have email addresses (+1 credit)\nrequire_phone_numbers\tboolean\tfalse\tOnly return profiles that have phone numbers (+1 credit)\nrequire_phones_or_emails\tboolean\tfalse\tOnly return profiles with either phone or email (+1 credit)\ninsights\tboolean\tfalse\tAI-generated insights per result explaining match relevance (+1 credit per result). Not available for light type\nprofile_scoring\tboolean\tfalse\tInclude AI relevance score (0-1) per result (+1 credit)\nhigh_freshness\tboolean\tfalse\tPrioritize recently updated profiles (+2 credits). Not available for light type\nforce_new\tboolean\tfalse\tForce fresh search, ignore cached results\ncustom_filters\tobject\tomit\tStructured filters for precise targeting (see Custom Filters below)\ncallback_url\tstring\tomit\tWebhook URL for async results delivery\nCustom Filters\n\nPass as a custom_filters object to narrow results beyond the natural language query.\n\nArray fields (pass as arrays of strings):\n\nFilter\tDescription\nlocations\tGeographic locations (e.g., [\"San Francisco\", \"New York\"])\nlanguages\tLanguages spoken (e.g., [\"English\", \"Spanish\"])\ntitles\tJob titles (e.g., [\"CTO\", \"VP Engineering\"])\nindustries\tIndustry sectors (e.g., [\"Technology\", \"Healthcare\"])\ncompanies\tCompany names, current or past (e.g., [\"Google\", \"Meta\"])\nuniversities\tUniversities attended (e.g., [\"Stanford\", \"MIT\"])\nkeywords\tProfile keywords (e.g., [\"machine learning\", \"AI\"])\ndegrees\tEducation degrees (e.g., [\"bachelor\", \"master\", \"phd\"])\nspecialization_categories\tAcademic specialization categories\n\nNumeric range fields (pass as integers):\n\nFilter\tDescription\nmin_linkedin_followers / max_linkedin_followers\tLinkedIn follower count range\nmin_total_experience_years / max_total_experience_years\tTotal work experience range\nmin_current_experience_years / max_current_experience_years\tCurrent role tenure range\nmin_estimated_age / max_estimated_age\tEstimated age range\n\nExact match fields:\n\nFilter\tType\tDescription\nfirst_name\tstring\tExact first name match\nmiddle_name\tstring\tExact middle name match\nlast_name\tstring\tExact last name match\ngender\tstring\t\"male\" or \"female\"\nstudied_at_top_universities\tboolean\tAttended a top-ranked university\nExamples\n\nBasic search:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Software engineers at Google in San Francisco\", \"limit\": 10}' | nyne_parse > /tmp/nyne_search.json\n\njq '{status: .data.status, request_id: .data.request_id}' /tmp/nyne_search.json\n\n\nWith emails and phone numbers:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Marketing directors at tech startups in Austin\", \"limit\": 25, \"show_emails\": true, \"show_phone_numbers\": true}' | nyne_parse > /tmp/nyne_search.json\n\n\nWith custom filters:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\n    \"query\": \"Engineering leaders in fintech\",\n    \"limit\": 20,\n    \"type\": \"premium\",\n    \"show_emails\": true,\n    \"custom_filters\": {\n      \"locations\": [\"New York\", \"San Francisco\"],\n      \"titles\": [\"CTO\", \"VP Engineering\", \"Head of Engineering\"],\n      \"min_total_experience_years\": 10,\n      \"industries\": [\"Financial Services\", \"Technology\"]\n    }\n  }' | nyne_parse > /tmp/nyne_search.json\n\n\nLight search (fast, 1 credit):\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Data scientists at Amazon\", \"type\": \"light\", \"limit\": 10}' | nyne_parse > /tmp/nyne_search.json\n\n\nWith AI scoring and insights:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"AI researchers in healthcare\", \"type\": \"premium\", \"profile_scoring\": true, \"insights\": true, \"limit\": 10}' | nyne_parse > /tmp/nyne_search.json\n\n\nWith freshness priority:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Product managers who recently changed jobs\", \"type\": \"premium\", \"high_freshness\": true, \"show_emails\": true}' | nyne_parse > /tmp/nyne_search.json\n\n\nRequire contact info:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"query\": \"Sales directors at SaaS companies\", \"require_emails\": true, \"show_emails\": true, \"limit\": 50}' | nyne_parse > /tmp/nyne_search.json\n\n\nSubmit response:\n\n{\n  \"success\": true,\n  \"data\": {\n    \"request_id\": \"abc12345_1737123456_1234\",\n    \"status\": \"completed\",\n    \"results\": [...],\n    \"offset\": 0,\n    \"limit\": 10,\n    \"total_stored\": 47,\n    \"total_estimate\": 2500,\n    \"has_more\": true,\n    \"next_cursor\": \"eyJvIjoxMCwiciI6ImFiYzEyMzQ1XzE3MzcxMjM0NTZfMTIzNCJ9\",\n    \"from_cache\": false,\n    \"credits_charged\": 7\n  },\n  \"timestamp\": \"2026-02-19T...\"\n}\n\n\nNote: The POST may return status: \"completed\" immediately (especially for cached or light searches) or status: \"processing\" requiring polling. Always check the status.\n\nPoll for Results (GET)\n\nEndpoint: GET https://api.nyne.ai/person/search?request_id={id}\n\nHeaders: Same X-API-Key and X-API-Secret as above.\n\nCheck status once\ncurl -s \"https://api.nyne.ai/person/search?request_id=$REQUEST_ID\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" | nyne_parse > /tmp/nyne_search.json\n\njq '{status: .data.status, total_stored: .data.total_stored}' /tmp/nyne_search.json\n\nFull polling loop\nSECONDS_WAITED=0\nTIMEOUT=600  # 10 minutes\n\nwhile [ $SECONDS_WAITED -lt $TIMEOUT ]; do\n  curl -s \"https://api.nyne.ai/person/search?request_id=$REQUEST_ID\" \\\n    -H \"X-API-Key: $NYNE_API_KEY\" \\\n    -H \"X-API-Secret: $NYNE_API_SECRET\" | nyne_parse > /tmp/nyne_search.json\n  STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)\n\n  echo \"[$(date +%H:%M:%S)] Status: $STATUS ($SECONDS_WAITED s)\"\n\n  case \"$STATUS\" in\n    completed)\n      jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json\n      jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n      break\n      ;;\n    failed)\n      echo \"Search failed:\"\n      jq '.data' /tmp/nyne_search.json\n      break\n      ;;\n    *)\n      sleep 5\n      SECONDS_WAITED=$((SECONDS_WAITED + 5))\n      ;;\n  esac\ndone\n\nif [ \"$STATUS\" != \"completed\" ] && [ \"$STATUS\" != \"failed\" ]; then\n  echo \"Timed out. Resume polling with request_id: $REQUEST_ID\"\nfi\n\nPagination\n\nAfter the initial search completes, paginate through results for free (cached results, no additional credits).\n\nCursor-based pagination (recommended)\n\nUse the next_cursor from the previous response:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"cursor\": \"eyJvIjoxMCwiciI6ImFiYzEyMzQ1XzE3MzcxMjM0NTZfMTIzNCJ9\"}' | nyne_parse > /tmp/nyne_search.json\n\njq '.data | {total_stored, offset, limit, has_more}' /tmp/nyne_search.json\njq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n\nOffset-based pagination\n\nUse request_id + offset from the original search:\n\ncurl -s -X POST \"https://api.nyne.ai/person/search\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $NYNE_API_KEY\" \\\n  -H \"X-API-Secret: $NYNE_API_SECRET\" \\\n  -d '{\"request_id\": \"abc12345_1737123456_1234\", \"offset\": 25, \"limit\": 25}' | nyne_parse > /tmp/nyne_search.json\n\njq '.data | {total_stored, offset, limit, has_more}' /tmp/nyne_search.json\njq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n\n\nPagination notes:\n\nPaginating through cached results is free — no additional credits charged\nMaximum 1000 results per search (offset + limit ≤ 1000)\nhas_more indicates whether more results are available\nnext_cursor is only present when has_more is true\nResults are cached for 30 days\nResponse Structure\n\nWhen status is completed:\n\n{\n  \"success\": true,\n  \"timestamp\": \"2026-02-19T...\",\n  \"data\": {\n    \"request_id\": \"abc12345_1737123456_1234\",\n    \"status\": \"completed\",\n    \"results\": [\n      {\n        \"displayname\": \"Jane Smith\",\n        \"headline\": \"Senior Software Engineer at Google\",\n        \"bio\": \"...\",\n        \"location\": \"San Francisco, CA\",\n        \"gender\": \"female\",\n        \"estimated_age\": 35,\n        \"total_experience_years\": 12,\n        \"is_decision_maker\": 1,\n        \"is_top_universities\": true,\n        \"languages\": [\"English\", \"Spanish\"],\n        \"interests\": {\n          \"work\": [\"software engineering\", \"machine learning\", \"distributed systems\"],\n          \"certification\": [\"AWS Solutions Architect\"]\n        },\n        \"patents\": [],\n        \"best_business_email\": \"jane@google.com\",\n        \"best_personal_email\": \"jane@gmail.com\",\n        \"altemails\": [\"j.smith@gmail.com\"],\n        \"fullphone\": [{\"fullphone\": \"+14155551234\", \"type\": \"mobile\"}],\n        \"social_profiles\": {\n          \"linkedin\": {\n            \"url\": \"https://www.linkedin.com/in/janesmith\",\n            \"username\": \"janesmith\",\n            \"connections\": 1243,\n            \"followers\": 542,\n            \"photo_url\": \"...\"\n          }\n        },\n        \"organizations\": [\n          {\n            \"name\": \"Google\",\n            \"title\": \"Senior Software Engineer\",\n            \"startDate\": \"3-2020\",\n            \"location\": \"San Francisco\",\n            \"company_website\": \"google.com\",\n            \"industries\": [\"Technology\"],\n            \"num_employees\": \"10001+\"\n          }\n        ],\n        \"schools_attended\": [\"Stanford University\"],\n        \"schools_info\": [\n          {\n            \"name\": \"Stanford University\",\n            \"degree\": \"Master's\",\n            \"title\": \"Computer Science\",\n            \"startDate\": \"2012\",\n            \"endDate\": \"2014\"\n          }\n        ],\n        \"score\": 0.92,\n        \"insights\": {\n          \"match_reasoning\": \"Strong match based on...\"\n        }\n      }\n    ],\n    \"offset\": 0,\n    \"limit\": 10,\n    \"total_stored\": 47,\n    \"total_estimate\": 2500,\n    \"has_more\": true,\n    \"next_cursor\": \"eyJvIjoxMCwi...\",\n    \"from_cache\": false,\n    \"credits_charged\": 7\n  }\n}\n\nResult Fields\nField\tType\tDescription\ndisplayname\tstring\tPerson's full name\nheadline\tstring\tCurrent job title/headline\nbio\tstring\tProfessional biography\nlocation\tstring\tGeographic location\ngender\tstring\t\"male\" or \"female\"\nestimated_age\tinteger\tEstimated age\ntotal_experience_years\tinteger\tYears of total work experience\nis_decision_maker\tinteger\tWhether person holds decision-making authority (1 = yes)\nis_top_universities\tboolean\tWhether person attended a top-ranked university\nlanguages\tarray\tLanguages spoken (array of strings)\ninterests\tobject\t{work: [...], certification: [...]} — work interests and certifications\npatents\tarray\tPatents held: {title, description, date, reference, url}\nbest_business_email\tstring\tPrimary business email (requires show_emails: true)\nbest_personal_email\tstring\tPrimary personal email (requires show_emails: true)\naltemails\tarray\tAlternative email addresses (requires show_emails: true)\nfullphone\tarray\tPhone numbers with type (requires show_phone_numbers: true). Each: {fullphone, type}\nsocial_profiles\tobject\tSocial profile data (see below)\norganizations\tarray\tWork history (see below)\nschools_attended\tarray\tUniversity names as strings\nschools_info\tarray\tDetailed education: {name, degree, major, startDate, endDate}\nscore\tnumber\tAI relevance score 0-1 (requires profile_scoring: true)\ninsights\tobject\tAI-generated match reasoning (requires insights: true)\nSocial Profiles Object\n{\n  \"linkedin\": {\n    \"url\": \"https://www.linkedin.com/in/...\",\n    \"username\": \"...\",\n    \"connections\": 1243,\n    \"followers\": 542,\n    \"photo_url\": \"...\"\n  }\n}\n\nOrganization Object\n{\n  \"name\": \"Windfall Bio\",\n  \"title\": \"Vice President of Software Engineering\",\n  \"startDate\": \"2024-08-01\",\n  \"endDate\": null,\n  \"location\": \"San Mateo, California, United States\",\n  \"company_website\": \"http://www.windfall.bio\",\n  \"company_linkedin_url\": \"https://www.linkedin.com/company/windfallbio\",\n  \"company_domain\": \"windfall.bio\",\n  \"industries\": [\"Manufacturing\"],\n  \"num_employees\": 37,\n  \"num_employees_range\": \"11-50\",\n  \"is_startup\": true,\n  \"is_b2b\": true,\n  \"is_b2c\": false,\n  \"is_saas\": false,\n  \"founded_in\": 2022,\n  \"latest_funding_round\": \"Series A\",\n  \"latest_funding_amount\": 28000000,\n  \"funding_total_usd\": 37000000,\n  \"annual_revenue\": 345000,\n  \"specialties\": [\"methane\", \"climate\", \"agtech\"],\n  \"technologies\": [\"Google Analytics\", \"AWS Lambda\", \"Webflow\"],\n  \"companyDesc\": \"...\",\n  \"logo_url\": \"...\"\n}\n\n\nOrganizations include rich company intelligence: funding data, tech stack, employee counts, and B2B/B2C/SaaS flags. Not all fields are present for every organization.\n\nResponse Metadata Fields\nField\tType\tDescription\ntotal_stored\tinteger\tNumber of results stored from this search\ntotal_estimate\tinteger\tEstimated total matching profiles\nhas_more\tboolean\tWhether more results are available for pagination\nnext_cursor\tstring\tOpaque pagination token for next page (present when has_more is true)\nfrom_cache\tboolean\tWhether results came from cache (30-day TTL)\ncredits_charged\tinteger\tTotal credits charged for this request\noffset\tinteger\tCurrent offset in result set\nlimit\tinteger\tResults per page\nUseful jq Filters\n\nAfter polling completes, the clean response is at /tmp/nyne_search.json:\n\n# Search metadata\njq '.data | {total_stored, total_estimate, has_more, credits_charged, from_cache}' /tmp/nyne_search.json\n\n# List all people (name + headline + location)\njq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json\n\n# All emails\njq '.data.results[] | {displayname, best_business_email, best_personal_email, altemails}' /tmp/nyne_search.json\n\n# Phone numbers\njq '.data.results[] | {displayname, fullphone}' /tmp/nyne_search.json\n\n# LinkedIn profiles\njq '.data.results[] | {displayname, linkedin: .social_profiles.linkedin.url}' /tmp/nyne_search.json\n\n# Work history per person\njq '.data.results[] | {displayname, orgs: [.organizations[] | {name, title}]}' /tmp/nyne_search.json\n\n# Decision makers only\njq '[.data.results[] | select(.is_decision_maker == true)] | length' /tmp/nyne_search.json\njq '[.data.results[] | select(.is_decision_maker == true) | {displayname, headline}]' /tmp/nyne_search.json\n\n# Sort by relevance score (if profile_scoring enabled)\njq '[.data.results | sort_by(-.score)[] | {displayname, headline, score}]' /tmp/nyne_search.json\n\n# Experience range\njq '.data.results[] | {displayname, total_experience_years} | select(.total_experience_years >= 10)' /tmp/nyne_search.json\n\n# Education\njq '.data.results[] | {displayname, schools: .schools_attended}' /tmp/nyne_search.json\n\n# Interests and certifications\njq '.data.results[] | {displayname, work_interests: .interests.work, certifications: .interests.certification}' /tmp/nyne_search.json\n\n# Patents\njq '.data.results[] | select(.patents | length > 0) | {displayname, patents: [.patents[] | {title, date}]}' /tmp/nyne_search.json\n\n# Company intelligence (funding, tech stack)\njq '.data.results[] | {displayname, companies: [.organizations[] | {name, funding_total_usd, latest_funding_round, num_employees, is_startup}]}' /tmp/nyne_search.json\n\n# Get next_cursor for pagination\njq -r '.data.next_cursor' /tmp/nyne_search.json\n\n# Count results\njq '.data.results | length' /tmp/nyne_search.json\n\nError Handling\nHTTP Code\tError\tDescription\n400\tinvalid_parameters\tInvalid parameter value or missing query\n400\tinvalid_custom_filters\tMalformed custom_filters object\n401\tinvalid_credentials\tInvalid API key/secret\n404\trequest_not_found\tInvalid request_id for status check (GET only)\n429\trate_limit_exceeded\tToo many requests\n429\tinsufficient_credits\tNot enough credits for this search\n500\tinternal_error\tServer error\nSearch Tiers & When to Use Each\nFast Search — type: \"light\" (1 credit per result)\n\nBasic search with fast results in 3-40 seconds. Best for quick lookups when you need a broad list of names and don't need deep profile data. AI features (insights, high_freshness) are NOT available for light type. Profile scoring is available.\n\n{\"query\": \"Software engineers at Google\", \"type\": \"light\", \"limit\": 50}\n\nSmart Search — type: \"medium\"\n\nBalanced tier between speed and quality. Use when you want better matching than light but don't need the full depth of premium. Supports all AI features.\n\n{\"query\": \"Engineering managers in fintech\", \"type\": \"medium\", \"limit\": 25}\n\nPro Search — type: \"premium\" (5 credits per result)\n\nComprehensive search taking 30-300 seconds. Best quality results with deepest profile matching. Required for maximum-quality insights and high_freshness results. Use when result quality matters more than speed.\n\n{\"query\": \"AI researchers at top universities\", \"type\": \"premium\", \"limit\": 10, \"insights\": true, \"profile_scoring\": true}\n\nAI-Powered Analysis Features\n\nThese features add intelligence on top of search results. Insights and High Freshness are NOT available for light type searches — use medium or premium.\n\nQuery Insights (insights: true, +1 credit per result)\n\nAI-generated analysis for each result explaining why this person matches your search query. Returns structured reasoning about the match relevance — how their background, role, and experience align with what you're looking for. Invaluable for qualifying leads or evaluating candidates at scale. Use when you need to understand the \"why\" behind each match, not just the \"who\".\n\n{\"query\": \"AI researchers in healthcare\", \"type\": \"premium\", \"insights\": true, \"limit\": 10}\n\nProfile Scoring (profile_scoring: true, +1 credit)\n\nAI relevance scoring that assigns each result a score from 0 to 1, where 1.0 is a perfect match. Use to rank and prioritize results by relevance. Works with all search tiers including light. Combine with insights for both a score and an explanation.\n\n{\"query\": \"Senior engineers at fintech startups\", \"profile_scoring\": true, \"limit\": 25}\n\nHigh Freshness (high_freshness: true, +2 credits)\n\nPrioritizes profiles that have been recently updated — people who recently changed jobs, updated their LinkedIn, or have fresh activity. Use when recency matters: hiring recently active candidates, targeting people who just moved to a new role, or finding profiles with current contact info. Not available for light type.\n\n{\"query\": \"Product managers who recently changed jobs\", \"type\": \"premium\", \"high_freshness\": true, \"show_emails\": true}\n\nCombining AI Features\n\nStack insights + scoring + freshness for maximum intelligence:\n\n{\n  \"query\": \"VP of Engineering at Series B startups in San Francisco\",\n  \"type\": \"premium\",\n  \"insights\": true,\n  \"profile_scoring\": true,\n  \"high_freshness\": true,\n  \"show_emails\": true,\n  \"limit\": 10\n}\n\nCredit Costs\n\nCredits are charged based on features used per request. Pagination within cached results is free.\n\nFeature\tCredits\tDescription\nFast Search (type: \"light\")\t1\tBasic search, fastest response (3-40 seconds)\nPro Search (type: \"premium\")\t5\tComprehensive search, best quality (30-300 seconds)\nSmart Ranking (profile_scoring, boolean)\t1\tAI-powered relevance scoring of results\nCandidate Insights (insights, boolean)\t1\tAI-generated insights about each result\nRealtime Profiles (high_freshness, boolean)\t2\tPrioritize recently updated profiles\nFilter Without Contact Data\t1\tSearch without email/phone enrichment\nEnrich Phones (show_phone_numbers, boolean)\t14\tInclude phone numbers in results. Significantly increases latency\nEnrich Emails (show_emails, boolean)\t2\tInclude email addresses in results. Significantly increases latency\nRequire Emails (require_emails, boolean)\t1\tOnly return profiles with email addresses\nRequire Phones (require_phone_numbers, boolean)\t1\tOnly return profiles with phone numbers\nRequire Contact Info (require_phones_or_emails, boolean)\t1\tOnly return profiles with phone OR email\nPagination (cached)\t0\tFree after initial search (30-day cache)\nRate Limits\nPer minute: 60 requests\nPer hour: 1,000 requests\nMonthly: Plan-dependent"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/MichaelFanous2/nyne-search",
    "publisherUrl": "https://clawhub.ai/MichaelFanous2/nyne-search",
    "owner": "MichaelFanous2",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/nyne-search",
    "downloadUrl": "https://openagent3.xyz/downloads/nyne-search",
    "agentUrl": "https://openagent3.xyz/skills/nyne-search/agent",
    "manifestUrl": "https://openagent3.xyz/skills/nyne-search/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/nyne-search/agent.md"
  }
}