Unicorn Screener API for AI Agents

Overview

What agents can do

Search and resolve any startup name via autocomplete
Trigger a full analysis and receive a PDF report by email
One free report per email, then $9 per additional report

Requires the web UI

POST /api/analyze (Turnstile CAPTCHA required)
POST /api/analyze-full (SSE streaming, browser fingerprint required)
Real-time progress stream and interactive disambiguation

Free tier: every email address gets one free report. Additional reports are $9 each via Lemon Squeezy. Rate limits apply equally to agents and human users.

Quick Start

Three steps to screen a startup as an AI agent.

Resolve the startup name

Use /api/autocomplete to search for the startup and get a confirmed name and website. This is the programmatic equivalent of typing into the search box and selecting from the dropdown.

Always verify before proceeding. Confirm that the returned name and website match what the user asked for. If the results look wrong or no results are returned, ask the user for clarification rather than triggering an analysis on the wrong company.

bash

curl "">https://unicornscreener.vc/api/autocomplete?q=mistral+ai"

json

{
  "results": [
    {
      "name": "Mistral AI",
      "website": "mistral.ai",
      "logo": "https://logo.dev/mistral.ai?token=..."
    }
  ]
}

Trigger the analysis

POST the confirmed startup name to /api/request-report. Use a random UUID as the fingerprint. The report will be sent to the provided email address within 5-15 minutes.

bash

curl -X POST "">https://unicornscreener.vc/api/request-report" \
  -H "Content-Type: application/json" \
  -d '{
    "startupName": "Mistral AI",
    "email": "user@example.com",
    "fingerprint": "'$(openssl rand -hex 16)'",
    "newsletter": false
  }'

json

{
  "success": true,
  "message": "Report queued. You'll receive it by email within 5-15 minutes."
}

Receive the PDF report

The report is emailed as a PDF attachment. It includes the full score (0-100), a breakdown across five dimensions, founder profiles, traction evidence, and an investment thesis.

Tip: tell the user to check their inbox in 5-15 minutes. The PDF is the canonical artifact — no need to poll for results.

GET /api/autocomplete

GET/api/autocompleteEdge runtime · No auth · 60s cache

Search for startups by name. Returns up to 6 suggestions with logo and website. Use this to resolve a user-provided startup name to a canonical, confirmed identity before triggering an analysis.

param	type	required	description
q	string	required	Startup name query. Minimum 2 characters, maximum 60.

bash

curl "">https://unicornscreener.vc/api/autocomplete?q=stripe"

json

{
  "results": [
    {
      "name": "Stripe",
      "website": "stripe.com",
      "logo": "https://img.logo.dev/stripe.com?token=..."
    },
    {
      "name": "Stripe Climate",
      "website": "climate.stripe.com",
      "logo": null
    }
  ]
}

The autocomplete may return multiple results for ambiguous names (e.g. "Stripe" vs "Stripe Climate"). Always show the user the options and wait for confirmation before sending to /api/request-report.

POST /api/request-report

POST/api/request-reportNode runtime · Rate-limited · Background job

Triggers a full analysis and delivers the PDF report by email. The request returns immediately with a confirmation; the analysis runs asynchronously in 5-15 minutes.

param	type	required	description
startupName	string	required	Company name to analyze. Use the confirmed name from /api/autocomplete for best results.
email	string	required	Email address where the PDF report will be delivered. Counts toward the 1 free report per email limit.
fingerprint	string	required	Any unique identifier for this request. Use crypto.randomUUID() or openssl rand -hex 16. Counted toward the 1 free report per fingerprint limit.
newsletter	boolean	optional	Set to false for agent requests.

bash

curl -X POST "">https://unicornscreener.vc/api/request-report" \
  -H "Content-Type: application/json" \
  -d '{
    "startupName": "Mistral AI",
    "email": "user@example.com",
    "fingerprint": "a3f1c290b4e5d8f0",
    "newsletter": false
  }'

Success response

json

{
  "success": true,
  "message": "Report queued. You'll receive it by email within 5-15 minutes."
}

Error responses

json

# 400 — Missing required fields
{ "error": "Missing required fields" }

# 429 — Free limit reached for this identifier
{
  "error": "limit_reached",
  "reason": "email"  # or "ip" or "fingerprint"
}

# 429 — Hourly rate limit exceeded
{
  "error": "rate_limited",
  "resetInSeconds": 1800
}

When you receive error: "limit_reached", the user has already claimed their free report with this identifier. Direct them to unicornscreener.vc to purchase additional reports at $9 each.

Rate Limits

endpoint	limit	cost
GET /api/autocomplete	No hard limit (60s cache)	Free
POST /api/request-report	1 free per IP + 1 per fingerprint + 1 per email	Free / $9

Agents follow the same limits as human users. The primary gate is email address: one free report per email, regardless of whether the request comes from a human or an AI agent. For bulk usage, each additional report is $9. There are no enterprise or volume plans at this time.

Handling 429 responses

json

# reason can be "ip", "fingerprint", or "email"
# When limit_reached: direct the user to unicornscreener.vc to purchase a report
{
  "error": "limit_reached",
  "reason": "email"
}

# When rate_limited: retry after the indicated number of seconds
{
  "error": "rate_limited",
  "resetInSeconds": 1800
}

LLM Tips

Guidance for integrating Unicorn Screener as a tool in Claude, GPT, or custom AI agents.

Tool schema (Claude / OpenAI)

Add this to your tool definitions to let the LLM call Unicorn Screener.

Always autocomplete first

Before calling /api/request-report, always run /api/autocomplete and confirm the result with the user. This prevents analyzing the wrong company and wasting the free report.

Email delivery gap

Reports arrive 5-15 minutes after the request. Tell the user to check their inbox. The PDF is the canonical artifact, not a separate JSON endpoint.

Confirm before triggering

Never call /api/request-report without user confirmation of the startup identity. The free report is one-shot per email — wasting it on the wrong company means the user has to pay $9 to re-screen.

Tool definition (copy-paste ready)

json

{
  "name": "screen_startup",
  "description": "Screen a startup on its unicorn potential using Unicorn Screener. Always call autocomplete first to confirm the company name with the user before triggering an analysis.",
  "input_schema": {
    "type": "object",
    "properties": {
      "action": {
        "type": "string",
        "enum": ["autocomplete", "request_report"],
        "description": "Which API to call. Use 'autocomplete' first to resolve the company, then 'request_report' once the user has confirmed the identity."
      },
      "name": {
        "type": "string",
        "description": "Startup name to search or analyze."
      },
      "email": {
        "type": "string",
        "description": "User email for report delivery. Required for 'request_report' action only."
      }
    },
    "required": ["action", "name"]
  }
}

System prompt snippet

Drop this into your agent's system prompt.

bash

You can screen startups using Unicorn Screener (unicornscreener.vc).

Workflow:
1. Call /api/autocomplete?q=<name> to resolve the startup name.
   Show the user the top result and confirm it is the right company before proceeding.
2. Once confirmed, ask the user for their email, then call /api/request-report
   with the confirmed name, email, a random fingerprint, and newsletter: false.
   Inform the user the report will arrive by email in 5-15 minutes.

The first report is free per email address. Additional reports cost $9 each
at unicornscreener.vc. Never trigger an analysis without user confirmation of
the startup identity — the free report is one-shot.

unicornscreener.vc ·Contact us

Unicorn Screenerfor AI Agents

Overview

Quick Start

Resolve the startup name

Trigger the analysis

Receive the PDF report

GET /api/autocomplete

POST /api/request-report

Success response

Error responses

Rate Limits

Handling 429 responses

LLM Tips

Tool schema (Claude / OpenAI)

Always autocomplete first

Email delivery gap

Confirm before triggering

Tool definition (copy-paste ready)

System prompt snippet

Unicorn Screener
for AI Agents