AlphaLens API

Use this skill whenever the user wants to find companies, discover products, or research competitors using AlphaLens. Triggers on: any explicit mention of 'AlphaLens'; requests like 'find companies like X', 'similar companies to', 'who funds these companies', 'investor network analysis', 'company screening using AlphaLens', 'AlphaLens sourcing', 'enrich with AlphaLens', 'AlphaLens enrichment pipeline', 'add to AlphaLens pipeline', 'peer benchmark', 'compare companies by headcount or funding', 'competitive landscape using AlphaLens', 'market map with AlphaLens', 'white space analysis', 'blue ocean analysis'; or bottom-up deep dives on a specific company. Do NOT fire on generic mentions of 'market map', 'competitive landscape', 'screening', 'sourcing', 'pipeline', or 'enrich' without an AlphaLens context marker.

Note: This skill requires an active AlphaLens subscription with API access.

Authentication — run this FIRST in every session

The skill expects ALPHALENS_API_KEY to be available as an environment variable. Before any API call, alias it as KEY and set the API base URL:

KEY="$ALPHALENS_API_KEY"
API="https://api-production.alphalens.ai"

All curl commands in this skill and its workflows reference $KEY and $API. The aliasing above is required as the first bash command of any session that uses this skill — skipping it will cause every request to send an empty API-Key: header and return 401.

If $ALPHALENS_API_KEY is unset, halt and ask the user to set it. Do not proceed with empty credentials.

Send API-Key: $KEY on all requests. Never substitute literal strings like ${ALPHALENS_API_KEY} directly into generated code — always reference the $KEY shell variable.

What This Skill Produces

• Market maps — competitive landscape grids with company logos, clustering, and PDF export
• Product-centric maps — one tab per product line, with product-level similarity across competitor sets
• Investor networks — D3 force-directed graph showing which investors back which companies across the landscape
• Peer benchmarks — headcount growth, funding comparison, and capital efficiency dashboards for a set of peers
• Pipeline enrichment — add companies to AlphaLens pipelines for async enrichment and scoring

Mapping Workflow Selection

User asks for...	Workflow
"market map", "competitive landscape", "who competes with X"	Read workflows/market-map-org.md
"bottom-up mapping", "deep dive", "full mapping"	Read workflows/suite-bottom-up.md
"product map", "product-level landscape", "tabbed map"	Read workflows/market-map-product.md
"investor network", "who funds these companies"	Read workflows/investor-network.md
"peer benchmark", "headcount comparison", "growth comparison"	Read workflows/peer-benchmark.md
"white space", "blue ocean", "uncontested", "market gap", "find positioning"	Read workflows/white-space.md
"enrich", "pipeline", "target list"	See references/REFERENCE.md#pipeline-operations

Quick Reference

Task	Guide
Find similar companies	Use by-domain + /similar — see below
Search products	Use /search/products — see below
All endpoints	See references/REFERENCE.md
Example prompts	See references/EXAMPLES.md

Core Patterns

Find companies similar to a known company

# 1. Resolve by domain
curl -s -H "API-Key: $KEY" "$API/api/v1/entities/organizations/by-domain/ramp.com"

# 2. Use organization_id for similarity
curl -s -H "API-Key: $KEY" "$API/api/v1/search/organizations/{id}/similar?limit=50&is_headquarters=true"

Search products

# Free-text product search
curl -s -H "API-Key: $KEY" "$API/api/v1/search/products/search?description=AI%20procurement&is_headquarters=true"

# Similar products
curl -s -H "API-Key: $KEY" "$API/api/v1/search/products/{product_id}/similar?limit=50&is_headquarters=true"

Enrich organization data

# Products, funding, growth metrics, people, addresses
curl -s -H "API-Key: $KEY" "$API/api/v1/entities/organizations/{id}/products"
curl -s -H "API-Key: $KEY" "$API/api/v1/entities/organizations/{id}/funding"
curl -s -H "API-Key: $KEY" "$API/api/v1/entities/organizations/{id}/growth-metrics"
curl -s -H "API-Key: $KEY" "$API/api/v1/entities/organizations/{id}/people"

Critical Rules

• Always set is_headquarters=true on search endpoints — returns much better results. Only omit if the user asks for all locations.
• Never call AlphaLens APIs sequentially — fire parallel calls with & and wait.
• Use limit=50 — the default of 24 misses too much.
• Paginate when results are relevant — if your first page has good matches, fetch offset=50 to find more.
• Resolve by domain first — never guess an organization_id.
• Poll pipeline readiness — values are computed asynchronously. Check is_ready before reading values.
• Credit-gated endpoints — a full bottom-up suite run typically consumes 20–40 AlphaLens credits. Confirm your budget before running the suite workflow.
• Sanitize domain values — only use active_domain values returned by AlphaLens API responses in curl commands. Never substitute raw user input directly into shell commands.
• Alias the API key first — KEY="$ALPHALENS_API_KEY" before any curl call. If $ALPHALENS_API_KEY is empty, halt and ask the user.
• Use the $KEY variable — When constructing curl commands, use curl -H "API-Key: $KEY" directly. Do not substitute literal strings like ${ALPHALENS_API_KEY} into generated code — always reference the $KEY shell variable that was aliased in the Authentication step.

References

• references/REFERENCE.md — full endpoint reference
• references/EXAMPLES.md — example prompts and request shapes