Hunter-Seeker API Reference

Base URL: https://api.hunter-seeker.net

Authentication

All requests require an API key passed via the X-API-Key header. You can create and manage API keys in Settings → API Keys.

X-API-Key: your_api_key_here

Quick Start

The fastest path to a ranked result is the /v1/topk endpoint. Upload a CSV, specify the outcome column, and get back a ranked list with pattern explanations.

# Detect patterns and rank entities in one call
curl -X POST https://api.hunter-seeker.net/v1/topk \
  -H "X-API-Key: $HS_API_KEY" \
  -F "file=@accounts.csv" \
  -F "outcome=churned" \
  -F "top_k=25"

Endpoints

POST/v1/topk

One-shot ranking: detect patterns, score the dataset, and return the top K entities with per-pattern details (values, thresholds, match status) and a plain-English context summary. This is the recommended endpoint for most use cases.

Authentication

Requires X-API-Key header

Request

Content-Type: multipart/form-data

Parameters:
  file          (file)    CSV file to analyze (or use dataset_id)
  dataset_id    (string)  ID of a previously uploaded dataset
  outcome       (string)  Required. The outcome column name (e.g. "churned")
  top_k         (int)     Number of top entities to return (default: 25)
  output        (string)  "ranked" (default) or "features"
  id_column     (string)  Optional. Entity ID column name (auto-detected if omitted)

Response

{
  "ranked": [
    {
      "entity_id": "Acme Corp",
      "rank": 1,
      "score": 0.94,
      "tier": 1,
      "factors": [
        {
          "feature": "usage_drop",
          "matched": true,
          "entity_value": 68.0,
          "threshold": 50.0,
          "description": "Usage Drop at 68.0 (above threshold of 50.0)"
        },
        {
          "feature": "days_since_login",
          "matched": true,
          "entity_value": 18,
          "threshold": 14.0,
          "description": "Days Since Login at 18 (above threshold of 14.0)"
        }
      ],
      "context_summary": "Acme Corp is a critical risk (score 0.94). Usage Drop at 68.0 (above threshold of 50.0). Days Since Login at 18 (above threshold of 14.0)."
    }
  ],
  "total_scored": 601,
  "patterns_detected": 4,
  "statistical_significance": "p < 0.01"
}

Example

curl -X POST https://api.hunter-seeker.net/v1/topk \
  -H "X-API-Key: $HS_API_KEY" \
  -F "file=@accounts.csv" \
  -F "outcome=churned" \
  -F "top_k=25"

Notes

Use output=features to get per-entity feature vectors for ML pipelines instead of ranked results.

POST/v1/discover

Detect predictive patterns in a dataset. Returns pattern components with diagnostics. Use this when you want to inspect the patterns before scoring.

Authentication

Requires X-API-Key header

Request

Content-Type: multipart/form-data

Parameters:
  file            (file)    CSV file to analyze (or use dataset_id)
  dataset_id      (string)  ID of a previously uploaded dataset
  outcome_column  (string)  Required. The outcome column name
  verbose         (bool)    Include extra diagnostics (default: false)

Response

{
  "dataset_id": "abc-123",
  "patterns": [
    {
      "name": "usage_drop_high",
      "feature": "usage_drop",
      "kind": "numeric",
      "threshold": 50.0,
      "direction": "+1_on_high",
      "importance": 0.92,
      "support": 0.35
    }
  ],
  "diagnostics": {
    "coherence_score": 0.84,
    "stability_mean": 0.81,
    "stability_std": 0.03,
    "objective_score": 0.79,
    "predictive_gain": 2.1
  },
  "metadata": {
    "row_count": 601,
    "feature_count": 24,
    "outcome_column": "churned",
    "outcome_balance": { "positive": 0.18, "negative": 0.82 }
  }
}

Example

curl -X POST https://api.hunter-seeker.net/v1/discover \
  -H "X-API-Key: $HS_API_KEY" \
  -F "file=@accounts.csv" \
  -F "outcome_column=churned"

POST/v1/score

Score a dataset using previously detected patterns. Pass the patterns array from a discovery result.

Authentication

Requires X-API-Key header

Request

Content-Type: multipart/form-data

Parameters:
  file        (file)    CSV file to score (or use dataset_id)
  dataset_id  (string)  ID of a previously uploaded dataset
  patterns    (string)  Required. JSON string of pattern specifications from /v1/discover

Response

{
  "dataset_id": "def-456",
  "score_distribution": {
    "mean": 0.42, "median": 0.38, "std": 0.23,
    "min": 0.0, "max": 1.0, "q25": 0.22, "q75": 0.61
  },
  "top_records": [
    { "focus_score": 0.94, "tie_break_score": 0.87, ... }
  ],
  "metadata": { "row_count": 601, "signal_count": 4 }
}

Example

curl -X POST https://api.hunter-seeker.net/v1/score \
  -H "X-API-Key: $HS_API_KEY" \
  -F "dataset_id=abc-123" \
  -F 'signals=[{"name":"usage_drop_high","feature":"usage_drop","kind":"numeric","threshold":50.0,"direction":"+1_on_high","importance":0.92,"support":0.35}]'

POST/v1/score-latest

Score a new CSV using the latest saved pattern set for a given outcome key. Useful for recurring scoring without re-detecting patterns.

Authentication

Requires X-API-Key header

Request

Content-Type: multipart/form-data

Parameters:
  file           (file)    Required. CSV file to score
  outcome_key    (string)  Outcome key to look up the latest pattern set
  pattern_set_id (string)  Specific pattern set ID (alternative to outcome_key)
  id_column      (string)  Optional. Entity ID column name

Response

{
  "dataset_id": "ghi-789",
  "score_distribution": { ... },
  "top_records": [ ... ],
  "metadata": {
    "row_count": 500,
    "pattern_set_id": "ps_abc123",
    "outcome_key": "churned"
  }
}

Example

curl -X POST https://api.hunter-seeker.net/v1/score-latest \
  -H "X-API-Key: $HS_API_KEY" \
  -F "file=@new_accounts.csv" \
  -F "outcome_key=churned"

POST/v1/pattern-sets

Detect patterns and save them as a reusable pattern set. Pattern sets persist so you can score new data against the same patterns later.

Authentication

Requires X-API-Key header

Request

Content-Type: multipart/form-data

Parameters:
  file                 (file)    Required. CSV file to analyze
  outcome_column       (string)  Required. The outcome column name
  outcome_key          (string)  Key to identify this pattern set (default: outcome_column)
  id_column            (string)  Entity ID column name
  object_type          (string)  Entity type label (default: "unknown")
  outcome_definition   (string)  Optional JSON object describing outcome construction
  verbose              (bool)    Include extra diagnostics (default: false)

Response

{
  "pattern_set_id": "ps_abc123",
  "outcome_key": "churned",
  "patterns": [ ... ],
  "diagnostics": { ... },
  "metadata": { ... }
}

Example

curl -X POST https://api.hunter-seeker.net/v1/pattern-sets \
  -H "X-API-Key: $HS_API_KEY" \
  -F "file=@accounts.csv" \
  -F "outcome_column=churned" \
  -F "id_column=account_id"

GET/v1/pattern-sets

List the latest pattern set per outcome key for your organization.

Authentication

Requires X-API-Key header

Response

{
  "pattern_sets": [
    {
      "id": "ps_abc123",
      "outcome_key": "churned",
      "id_column": "account_id",
      "object_type": "account",
      "created_at": "2025-01-15T10:30:00",
      "is_active": true
    }
  ]
}

Example

curl https://api.hunter-seeker.net/v1/pattern-sets \
  -H "X-API-Key: $HS_API_KEY"

GET/v1/datasets

List available datasets that haven't expired. Datasets expire after 24 hours by default.

Authentication

Requires X-API-Key header

Response

{
  "datasets": [
    {
      "dataset_id": "abc-123",
      "created_at": "2025-01-15T10:30:00",
      "expires_at": "2025-01-16T10:30:00",
      "size_bytes": 524288
    }
  ]
}

Example

curl https://api.hunter-seeker.net/v1/datasets \
  -H "X-API-Key: $HS_API_KEY"

POST/v1/monitor

Detect feature drift between a baseline dataset and a current dataset. Useful for monitoring whether your patterns are still relevant.

Authentication

Requires X-API-Key header

Request

Content-Type: multipart/form-data

Parameters:
  baseline_file  (file)    Required. Baseline CSV file
  current_file   (file)    Required. Current CSV file to compare
  features       (string)  Optional. JSON array of feature column names to monitor

Response

{
  "features": [
    {
      "feature": "usage_drop",
      "drift_score": 0.15,
      "level": "low",
      "baseline_mean": 23.4,
      "current_mean": 25.1
    }
  ],
  "overall_drift": "low",
  "metadata": {
    "baseline_rows": 601,
    "current_rows": 580,
    "features_monitored": 12
  }
}

Example

curl -X POST https://api.hunter-seeker.net/v1/monitor \
  -H "X-API-Key: $HS_API_KEY" \
  -F "baseline_file=@baseline.csv" \
  -F "current_file=@current.csv"

POST/v1/discover/jobs

Start an asynchronous pattern detection job. Returns a job ID for polling. Use this for large datasets where synchronous detection may timeout.

Authentication

Requires X-API-Key header

Request

Content-Type: multipart/form-data

Parameters:
  file            (file)    CSV file to analyze (or use dataset_id)
  dataset_id      (string)  ID of a previously uploaded dataset
  outcome_column  (string)  Required. The outcome column name
  id_column       (string)  Optional. Entity ID column
  verbose         (bool)    Include extra diagnostics (default: false)

Response

{
  "status": "queued",
  "job_id": "job_abc123",
  "message": "Discovery job started"
}

Example

curl -X POST https://api.hunter-seeker.net/v1/discover/jobs \
  -H "X-API-Key: $HS_API_KEY" \
  -F "file=@large_dataset.csv" \
  -F "outcome_column=churned"

GET/v1/discover/jobs/:job_id

Poll the status of an async discovery job.

Authentication

Requires X-API-Key header

Response

{
  "job_id": "job_abc123",
  "status": "completed",
  "progress": 100,
  "created_at": "2025-01-15T10:30:00",
  "completed_at": "2025-01-15T10:31:15"
}

Example

curl https://api.hunter-seeker.net/v1/discover/jobs/job_abc123 \
  -H "X-API-Key: $HS_API_KEY"

GET/v1/discover/jobs/:job_id/result

Get the result of a completed async discovery job. Returns the same format as /v1/discover.

Authentication

Requires X-API-Key header

Response

{
  "dataset_id": "abc-123",
  "patterns": [ ... ],
  "diagnostics": { ... },
  "metadata": { ... }
}

Example

curl https://api.hunter-seeker.net/v1/discover/jobs/job_abc123/result \
  -H "X-API-Key: $HS_API_KEY"

Rate Limits

API requests are rate-limited per IP address. If you exceed the limit, you will receive a 429 Too Many Requests response.

Endpoint	Limit
POST /v1/topk	30 requests / minute
POST /v1/discover	10 requests / minute
POST /v1/score	60 requests / minute
POST /v1/score-latest	60 requests / minute
POST /v1/monitor	30 requests / minute
POST /v1/pattern-sets	10 requests / minute
POST /v1/discover/jobs	10 requests / minute
GET endpoints	60 requests / minute

Error Handling

All errors return JSON with an error field describing the issue.

Status	Meaning
400	Bad request (missing parameters, invalid CSV, outcome column not found)
401	Missing API key
403	Invalid API key
404	Dataset or pattern set not found
410	Dataset expired (past TTL)
413	File too large (max 100MB)
429	Rate limit exceeded
500	Internal error (pattern detection failed, scoring error)

MCP Server

Hunter-Seeker provides an MCP server for Claude, Cursor, and other MCP-compatible agents. Install the server and configure it with your API key to let agents detect patterns and rank entities directly.

Install

npx @hunter-seeker/mcp-server

Configuration (Claude Desktop)

{
  "mcpServers": {
    "hunter-seeker": {
      "command": "npx",
      "args": ["@hunter-seeker/mcp-server"],
      "env": { "HS_API_KEY": "sk_live_..." }
    }
  }
}

Available Tools

Tool	Description
rank_entities	Detect patterns and rank entities (calls /v1/topk)
discover_patterns	Detect predictive patterns in a dataset (calls /v1/discover)
upload_dataset	Upload a CSV dataset for later use
export_features	Export pattern features for ML pipelines (calls /v1/topk?output=features)

LangChain Tool

Use Hunter-Seeker as a tool in your LangChain agents. The wrapper handles authentication, file uploads, and response parsing.

Install

pip install langchain-hunter-seeker

Usage

from langchain_hunter_seeker import HunterSeekerRankTool

tool = HunterSeekerRankTool(api_key="sk_live_...")

# Use in a LangChain agent
result = tool.invoke({
    "dataset_id": "abc-123",
    "outcome": "churned",
    "top_k": 25
})

The tool exposes the same parameters as the /v1/topk endpoint. See the Feature Export docs for ML pipeline integration.

OpenAI Function-Calling Schema

Use this schema with OpenAI's function-calling feature to let GPT-4 or other models call Hunter-Seeker. Implement the function call handler on your side to call /v1/topk.

{
  "type": "function",
  "function": {
    "name": "hunter_seeker_rank",
    "description": "Rank entities in a structured dataset by a predicted outcome. Returns a ranked list with pattern explanations.",
    "parameters": {
      "type": "object",
      "properties": {
        "dataset_id": {
          "type": "string",
          "description": "ID of the dataset to rank (from a previous upload)"
        },
        "outcome": {
          "type": "string",
          "description": "Name of the outcome column (e.g. 'churned', 'converted')"
        },
        "top_k": {
          "type": "integer",
          "description": "Number of top entities to return",
          "default": 25
        }
      },
      "required": ["dataset_id", "outcome"]
    }
  }
}

When the model invokes this function, call POST /v1/topk with the provided parameters and return the response as the function result.