# StartupSeeker API v4

REST base URL: https://startup-seeker.com/api/v4 · OpenAPI: https://startup-seeker.com/api/v4/openapi.json · MCP: https://startup-seeker.com/mcp/v4 · Interactive docs: https://startup-seeker.com/api-docs

## StartupSeeker API

Search, filter and export startups, investors, funding rounds and exits; enrich your own company lists; and keep them in saved lists. Every response is JSON with the same shape, every list pages the same way, and every job follows the same lifecycle.

- **REST base URL:** `https://startup-seeker.com/api/v4`
- **Authentication:** `Authorization: Bearer ssk_live_…` with a key from [your API settings](/account/api-keys).
- **AI assistants:** connect Claude, ChatGPT or Cursor to `https://startup-seeker.com/mcp/v4`; it speaks the same filters. See [Using with AI agents](#ai-agents).
- **Machine-readable:** [OpenAPI 3.1](/api/v4/openapi.json) · [Markdown guide](/api/v4/docs.md) · [llms.txt](/llms.txt)

## Your first request

```bash
curl https://startup-seeker.com/api/v4/startups/search \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"hq_country": "DE", "industries": {"any": ["fintech"]}}, "fields": ["name", "domain", "total_funding_usd"], "sort": ["-total_funding_usd"], "limit": 2}'
```

```json
{
  "data": [
    { "id": "c587ec6d-beaa-5057-a7e8-750b8f10513a", "name": "Deutsche Bank", "domain": "db.com", "total_funding_usd": 1500000000 },
    { "id": "556dd90f-78fe-526b-b0bd-3e8c1fba4eff", "name": "Owwn", "domain": "owwn.com", "total_funding_usd": 900100000 }
  ],
  "page": { "next_cursor": "c1.a.bZBd…", "total": { "value": 178, "exact": true } },
  "meta": { "request_id": "3f0c…", "cost_usd_cents": 1, "applied_filter": { "hq_country": { "eq": "DE" }, "industries": { "any": ["fintech"] } } }
}
```

A successful read costs 1¢. Dates are UTC; money is USD.

## Next steps

1. **Get the next page:** send only `page.next_cursor` back: `{"cursor": "c1.a.bZBd…"}`. See [Pagination](#pagination).
2. **Open a record:** `GET /startups/stripe.com?expand=funding_rounds,investors`. See [Expand related records](#expand).
3. **Search by meaning:** `{"query": "sodium-ion battery cells"}` ranks startups semantically. See [Semantic search](#semantic).
4. **Get everything as a file:** `POST /exports` with the same filter. See [Recipes](#recipes).
5. **Find out what you can filter on:** `GET /schema/startups`, free and public.

## Authentication

Send your key as a Bearer token on every request:

```bash
curl https://startup-seeker.com/api/v4/account -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"
```

- Create and revoke keys at [/account/api-keys](/account/api-keys). Keys start with `ssk_live_`; keep them server-side.
- `GET /schema`, `GET /schema/{collection}`, `GET /industries`, `/api/v4/openapi.json` and the docs need no key.
- API keys and connected AI apps (OAuth) share your account's balance and quotas.
- A missing, invalid or revoked key returns `401 UNAUTHORIZED`.

## Records and collections

| Collection | One record is | Refs accepted by `GET /{collection}/{ref}` |
| --- | --- | --- |
| `startups` | a company | UUID, domain, slug, LinkedIn URL |
| `investors` | a VC firm, angel group, corporate or accelerator | UUID, domain, slug, LinkedIn URL |
| `funding_rounds` | an accepted funding round | UUID |
| `exits` | an acquisition or IPO | UUID |

- **Fields:** `fields: ["name", "domain"]` returns only those (plus `id`). Without `fields`, the default set is returned. `GET /schema/{collection}` lists every field with its type, meaning and filter operators.
- **Identity:** `id` is stable. When two records are merged, the old ref resolves to the survivor, which carries `merged_from`.
- **Unknown, empty, not requested:** `null` means unknown; `[]` means known to be empty; a field you did not request is absent.
- **Many refs at once:** `POST /{collection}/match` takes up to 100 domains, UUIDs, LinkedIn URLs or names and answers per input, in order: `exact`, `candidates`, `not_found` or `invalid`. Names always return candidates, never an exact match, so you choose.

## Filters

A filter is a JSON object. **Sibling keys combine with AND.** A field maps to a value (equality) or to an object of operators (which also AND).

```json
{
  "filter": {
    "hq_country": "DE",
    "industries": { "any": ["fintech", "insurtech"] },
    "total_funding_usd": { "gte": 1000000, "lt": 50000000 },
    "last_round_at": { "gte": "-12m" },
    "text": "embedded payments -crypto",
    "or": [ { "hq_city": "Berlin" }, { "hq_city": "Munich" } ],
    "not": { "status": "shut_down" }
  }
}
```

`and`, `or`, `not` and `text` are reserved keys. `and` and `or` take arrays of filter objects; `not` takes one.

### Value forms

| You write | Scalar field (e.g. `hq_country`) | Tag field (e.g. `industries`) |
| --- | --- | --- |
| `"x"`, a number or `true` | equals x | contains x |
| `["a", "b"]` | is one of a, b | **error** `TAG_ARRAY_NEEDS_OPERATOR`: write `{"any": [...]}` or `{"all": [...]}` |
| `{"gte": 1, "lt": 5}` | operators (AND) | operators |
| `null`, `{}` or `[]` | **error**: use `{"exists": false}` for unknown values | **error** |

### Operators

| Operator | Meaning | Works on |
| --- | --- | --- |
| `eq`, `ne` | equals / has a value other than | text, numbers, dates, enums |
| `gt`, `gte`, `lt`, `lte`, `between` | comparisons; `between: [low, high]` is inclusive | numbers, money, dates |
| `in`, `nin` | is one of / has a value that is none of | text, numbers, enums, ids |
| `prefix` | starts with | text |
| `match` | full-text words: `"\"sodium ion\" OR \"na ion\" -lithium"` | text |
| `any`, `all`, `none` | contains any / all / none of | tags |
| `exists` | `true`: has a value; `false`: unknown | scalar fields (tags use `empty`) |
| `empty` | `true`: unknown or `[]`; `false`: at least one value | tags |
| `some`, `count`, `role` | related records, see below | relations |

`/schema/{collection}` lists the operators each field supports. Anything else returns `OPERATOR_NOT_SUPPORTED` with the list.

### Unknown values (NULL)

| Condition | Field unknown | Field `[]` | Field has a value |
| --- | --- | --- | --- |
| `eq`, `gt`, `in`, `any`, `all`, `match`, `prefix` | no match | no match | evaluated |
| `ne`, `nin` | **no match** (only known values) | — | evaluated |
| `none` | no match | match | evaluated |
| `exists: true` / `false` (scalar fields) | no / match | — | match / no |
| `empty: true` | match | match | no |
| `not: {…}` | the complement: **includes unknown** | complement | complement |

So `{"status": {"ne": "active"}}` means "known and not active", while `{"not": {"status": "active"}}` means "anything but active, including unknown". Missing `total_funding_usd` is unknown, not zero.

### Related records

- `{"investors": "sequoiacap.com"}` or `{"investors": {"in": ["sequoiacap.com", "a16z.com"]}}`: linked to any of these investors (domain or UUID). Add `"role": "lead"` for lead investors only.
- `{"funding_rounds": {"some": {"round_type": "seed", "amount_usd": {"gte": 1000000}}}}`: at least one round matches **all** conditions. Two separate `some` clauses (inside `and`) may be met by different rounds.
- `{"portfolio": {"count": {"gte": 5}, "some": {"hq_country": "BE"}}}` (investors): at least 5 distinct portfolio startups match. `deals` works the same for funding rounds and accepts `role`.
- Funding rounds and exits: `{"startup": {"some": {"hq_country": "FR"}}}` filters by the linked startup.

### Friendly values

| Field | You can write | Becomes |
| --- | --- | --- |
| dates | `"-30d"`, `"-12m"`, `"-2y"`, `"today"` | a UTC date, frozen when the first page runs |
| `hq_country` | `"DE"`, `"Germany"`, `"DEU"` | `"DE"` |
| `hq_city` | `"Berlin"`, `"New York"`, a GeoNames id | GeoNames ids; other cities: `GET /locations?q=…` |
| `industries` | a slug, a label like `"Battery Technology"`, or a group `"group:climate"` | slugs; see `GET /industries` |
| `stages` (investors) | `"Series A"`, `"pre seed"` | `"series a"`, `"pre-seed"` |

A value that matches exactly one canonical value is converted. Several matches return `VALUE_AMBIGUOUS` with candidates, and no match returns `VALUE_UNKNOWN` with `did_you_mean`. Nothing is silently widened: `"Series D"` is unknown (investor stages stop at `series c+`), and `"climate"` must be written as `"group:climate"`. The normalised filter is echoed in `meta.applied_filter`.

### Text search

`"text": "embedded payments -crypto"` (or `{"match": "…"}`) searches startup name and description (investors: name and thesis; rounds and exits: the linked startup). It matches whole words without stemming; use `OR` for variants and `-word` to exclude. For topics, [semantic search](#semantic) usually works better.

### Limits

Up to 3 nesting levels, 30 conditions, 100 values per array and a 16 KB body. Larger filters return `QUERY_TOO_COMPLEX`.

## Pagination and totals

Every list response has the same shape:

```json
{ "data": [ … ], "page": { "next_cursor": "c1.a.…", "total": { "value": 178, "exact": true } }, "meta": { "request_id": "…", "cost_usd_cents": 1 } }
```

- **Next page:** send only the cursor, plus an optional new `limit`: `POST /startups/search {"cursor": "c1.a.…"}`. On GET lists, use `?cursor=…`. The cursor carries the original filter, sort, fields and expands. Sending other parameters with a cursor is an error.
- **End:** `next_cursor` is `null`.
- **Page size:** `limit` 1–100 (default 25). Pages also shrink to fit the 1 MB response budget; then `page.shortened` is `true`, and the cursor continues exactly after the last row returned. Nothing is skipped or repeated.
- **Cursor lifetime:** 24 hours (semantic searches: 30 minutes). An expired cursor returns `410 CURSOR_EXPIRED`; run the query again. Cursors are bound to your account; a changed or foreign cursor returns `400 CURSOR_INVALID`.
- **Live pages:** pages read live data, so records updated between pages can move. Use an [export](#recipes) for one consistent read.
- **Totals:** `{"value": 178, "exact": true}`. Beyond 10,000 matches, `{"value": 10000, "exact": false}` means "at least". `{"value": null, "exact": false}` means the count did not finish in time. For exact large counts, use `POST /{collection}/aggregate`.

## Expand related records

`expand` nests related records into each result, e.g. `"expand": ["funding_rounds", "investors"]` on startups or `?expand=portfolio` on an investor.

- **To-many relations** are page objects, so a partial relation describes itself:

```json
"funding_rounds": { "data": [ … 20 rounds … ], "page": { "next_cursor": "c1.a.…", "total": { "value": 34, "exact": true } } }
```

  Continue with `GET /startups/{id}/funding_rounds?cursor=…`.
- **To-one relations** (`startup` and `acquirer` on rounds and exits) are plain objects or `null`.
- **Caps:** each relation returns up to its per-record cap (listed under `expand` in `/schema`; for example 20 funding rounds and 25 investors), and at most 2,000 related records per response.
- **Order:** funding rounds are newest first; a portfolio is alphabetical; co-investors are ordered by shared deals.
- **Sources:** `expand: ["sources"]` adds the public evidence behind the record's fields (URL, field, date), with the fields you requested first. Sources show where a value came from; they are not a guarantee that every field is sourced.
- **Related records as fields:** relation names are not fields; `fields: ["funding_rounds"]` returns `VALIDATION_FAILED` with a pointer to `expand`.

## Semantic search

For "companies doing X", rank startups by meaning instead of keywords:

```json
POST /startups/search
{ "query": "sodium-ion battery cells and materials", "filter": { "hq_region": { "any": ["europe"] } }, "fields": ["name", "domain"], "limit": 50 }
```

- `query` ranks by meaning; `similar_to: "northvolt.com"` finds look-alikes. Use one or the other, without `sort`. Startups only.
- Each row carries `_rank` (position), `_similarity` (0–1) and, where calibrated, `_match_percent`. Read down the list and stop where relevance falls off.
- `meta.ranking` states coverage: `within_filter` ranks every startup the filter allows; `post_filtered` means more than 10,000 startups match, so ranking is approximate and strong matches can be missed (narrow the filter to rank within it). Rankings are approximate and never exhaustive: `page.total` is the size of the ranked list, not of the market.
- `meta.search_id` identifies this exact ranking for 30 minutes. `POST /exports {"search_id": "…", "format": "csv"}` exports it in the same order, without ranking again.

## Jobs: exports and enrichments

Exports and enrichments run in the background as **jobs**. They share one status vocabulary:

```
quoting → awaiting_approval → queued → running → succeeded | partially_succeeded | failed
                    any non-final status → canceling → canceled
```

| Status | Meaning |
| --- | --- |
| `quoting` | working out the price (an enrichment's free VC-backability check runs here) |
| `awaiting_approval` | `quote` is ready; nothing has been charged |
| `queued`, `running` | approved; the quoted maximum is reserved |
| `succeeded` | done; read `result` (exports) or `/results` (enrichments) |
| `partially_succeeded` | done, but some items failed; they carry a message and are not charged |
| `failed` | the job could not run; reservations are refunded |
| `canceling` → `canceled` | work already in flight may finish and is settled |

- **Approve:** `POST /{jobs}/{id}/approve {"quote_id": "…"}`. This reserves `quote.max_cost_usd_cents`, the most you can be charged; only completed work is charged and the rest is refunded. A 0¢ quote starts automatically for API keys.
- **Quotes expire after 30 minutes but jobs don't.** Reading the job issues a fresh `quote_id`. Approving a stale quote returns `409 QUOTE_EXPIRED` with the current quote in `error.details.quote`. If the price rose, you get `409 PRICE_CHANGED`.
- **Waiting:** `GET /{jobs}/{id}?wait=10` returns as soon as the status changes, or after 10 seconds. Polling is free; or subscribe to [webhooks](#webhooks).
- **Finding jobs again:** set `client_reference` (your own id, up to 200 characters) on create, and list with `GET /exports?client_reference=…` or `GET /enrichments?client_reference=…`.

### Exports

`POST /exports` takes the same `collection`, `filter`, `sort`, `fields` and `expand` as search, plus `format` (`csv` or `jsonl`). Or send `search_id` from a semantic search to export that exact ranking. Up to 50,000 rows at 1¢ per 100 rows. Rows are selected when the export runs, usually seconds after approval, and never exceed the quoted row count; a `search_id` export keeps the ranking's exact membership and order. Expanded relations keep their per-record caps, and each row reports what was cut. When the job succeeds, `result.download_url` is valid for 5 minutes and renewed on every read; the file is kept for 7 days.

### Enrichments

```json
POST /enrichments
{ "companies": ["acme.com", "beta.io"], "update": { "details": true, "funding": { "freshness": "30d" } }, "client_reference": "crm-sync-42" }
```

- `companies`: up to 5,000 domains, `{"list_id": "…"}` or `{"csv": "…"}` (any website, domain or url column).
- Every company first gets a free VC-backability check. `check_only: true` stops there.
- `update` chooses what to refresh from the web: `details` (company details), `funding` and `founders`. `true` refreshes data older than 6 months; `{"freshness": "12m" | "6m" | "30d" | "always"}` sets the age (12m = 365 days, 6m = 183 days, 30d = 30 days). Data newer than that is not refreshed or charged. Without `update`, you get StartupSeeker's current data for free.
- `PATCH /enrichments/{id} {"update": …}` re-quotes before approval without repeating the check.
- `GET /enrichments/{id}/results` returns one row per company: `outcome`, the StartupSeeker `company` record, and per data type whether it was `updated`, `failed` or left alone.
- Connected AI apps (OAuth) need the enrichment permission granted on the StartupSeeker consent screen; API keys don't.

## Pricing and limits

| What | Price |
| --- | --- |
| Search, get, relation pages, match, aggregate, lists | 1¢ per successful request (also when the result is empty) |
| LinkedIn page read | 2¢ per request |
| Schema, industries, locations, account, docs, job status and results, corrections, webhooks | free |
| Export | 1¢ per 100 rows (unit price 100 micro-USD per row), charged on rows actually written |
| Enrichment: company details / funding / founders | 0.5¢ / 1¢ / 2¢ per company actually updated (5,000 / 10,000 / 20,000 micro-USD) |
| VC-backability check, StartupSeeker data without updates | free |

- Charges, balances and caps are whole USD cents. Unit prices are in micro-USD (1,000,000 = $1) because some are fractions of a cent. A job's line total is rounded up to whole cents.
- Failed requests are never charged a request fee. Job money is always visible on the job as `cost.reserved_usd_cents`, `charged_usd_cents` and `refunded_usd_cents`.
- `meta.cost_usd_cents` on each response is what that request cost.

**Default limits per account** (shared by all keys and connected apps; daily limits reset at UTC midnight):

| Limit | Default |
| --- | --- |
| Rows returned by reads | 20,000 per day |
| Exported rows | 50,000 per day |
| Concurrent heavy queries (search, get, aggregate) | 2 |
| Domains entering enrichment | 5,000 per day |
| Concurrent VC checks | 3 |
| Enrichment spend | $50 per job, $200 per day |

`GET /account` shows your balance (available and reserved), each limit, today's usage and reset times. Need more? Contact us.

## Idempotency and retries

Every `POST`, `PATCH` and `DELETE` that changes something accepts an `Idempotency-Key` header (1–200 printable characters). Use a new random key per intended change, and the same key when you retry that change.

- **Same key, same body:** the original response is replayed (same status and body, with `Idempotent-Replayed: true`). Replays are free, use no quota and work even at zero balance.
- **Same key, different body:** `409 IDEMPOTENCY_MISMATCH`.
- **Still running:** `409 IDEMPOTENCY_IN_PROGRESS` with `Retry-After`; retry the identical request.
- **Failed requests are not stored:** fix the request and retry with the same key.
- **Unknown outcome:** `500 MUTATION_OUTCOME_UNKNOWN`. Retry with the **same** key, never a new one; the effect happens at most once.
- Keys are scoped to your account, method and path, and kept for 24 hours. After that, find jobs again by `client_reference`.
- Search, match and aggregate are `POST` reads; they don't take keys.

## Errors and recovery

```json
{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "This quote expired or was replaced. Approve the current quote.",
    "param": "quote_id",
    "retryable": false,
    "doc_url": "https://startup-seeker.com/api-docs/v4#errors-quote-expired",
    "details": { "quote": { "quote_id": "…", "max_cost_usd_cents": 120 } }
  }
}
```

- `code` is stable and listed in the [error catalog](#errors-catalog), with one HTTP status per code. `param` names the field to fix; `hint` and `details` (such as `did_you_mean`, `candidates`, a new `quote`, `resets_at`) carry what you need to recover.
- **Retry** only when `retryable` is true: wait `Retry-After` seconds (or back off: 1 s, 2 s, 4 s … up to 30 s) and send the identical request, with the same `Idempotency-Key` for changes. `QUERY_TIMEOUT` deserves one retry; if it repeats, narrow the filter.
- **Don't retry** 4xx validation errors unchanged: fix the request.
- Every response has an `X-Request-Id` header; include it when you contact support.

## Rate limits

Authenticated responses carry the tightest current window:

| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | requests allowed in the window |
| `RateLimit-Remaining` | requests left |
| `RateLimit-Reset` | seconds until the window resets |

Above the limit you get `429 RATE_LIMITED` with `Retry-After`. Daily row, export and spend quotas return `429 QUOTA_EXCEEDED` with `details.resets_at`; check them any time with `GET /account`.

## Webhooks

Register an HTTPS endpoint and the events it should receive:

```bash
curl https://startup-seeker.com/api/v4/webhooks -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/startupseeker", "events": ["export.*", "enrichment.succeeded"]}'
```

The response includes `signing_secret` **once**; store it. `events` accepts event types, families such as `export.*`, or `*` (the default).

| Event | When |
| --- | --- |
| `export.awaiting_approval` | an export quote is ready |
| `export.succeeded`, `export.failed`, `export.canceled` | an export finished |
| `enrichment.awaiting_approval` | an enrichment quote is ready |
| `enrichment.succeeded`, `enrichment.partially_succeeded`, `enrichment.failed`, `enrichment.canceled` | an enrichment finished |
| `webhook.test` | you called `POST /webhooks/{id}/test` |

Each delivery is a `POST` with this body:

```json
{ "id": "evt_9f2c…", "type": "export.succeeded", "api_version": "v4", "created_at": "2026-11-15T10:00:00Z", "data": { "object": { "id": "…", "type": "export", "status": "succeeded", … } } }
```

`data.object` is the job as `GET` returns it, except that download links are left out; `GET` the job for a fresh link.

### Verify the signature

Headers: `StartupSeeker-Signature: t=1763200800,v1=5257a8…`, plus `StartupSeeker-Event-Id` and `StartupSeeker-Event-Type`. `v1` is the hex HMAC-SHA256 of `"{t}.{raw body}"` keyed with your signing secret (the whole string, as UTF-8). Verify the **raw** body before parsing JSON, compare in constant time, and reject timestamps more than 5 minutes away from now. While a rotated secret is still valid there are two `v1` values; accept either.

```js
import crypto from 'node:crypto';

// rawBody: the request body exactly as received (a string or Buffer), before JSON parsing.
export function verifyStartupSeekerSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const signatures = [];
  let timestamp = null;
  for (const part of String(header ?? '').split(',')) {
    const [key, value] = part.split('=');
    if (key === 't') timestamp = Number(value);
    if (key === 'v1') signatures.push(value);
  }
  if (!Number.isInteger(timestamp) || !signatures.length) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest();
  return signatures.some(signature => {
    const actual = Buffer.from(signature, 'hex');
    return actual.length === expected.length && crypto.timingSafeEqual(actual, expected);
  });
}
```

```python
import hashlib, hmac, time

def verify_startupseeker_signature(raw_body: bytes, header: str, secret: str, tolerance_seconds: int = 300) -> bool:
    timestamp, signatures = None, []
    for part in (header or "").split(","):
        key, _, value = part.partition("=")
        if key == "t" and value.isdigit():
            timestamp = int(value)
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or not signatures or abs(time.time() - timestamp) > tolerance_seconds:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, signature) for signature in signatures)
```

### Delivery

- Answer with any 2xx within 15 seconds. Otherwise the delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and then daily, for about 3 days. **Each attempt is signed again with a fresh `t`**; the event `id` and body stay the same.
- Deliveries can repeat or arrive out of order: deduplicate by `id`, and read the job for its current state.
- `GET /webhooks/{id}/deliveries` shows the last 30 days (status, attempts, last response). `POST /webhooks/{id}/deliveries/{delivery_id}/redeliver` sends one again.
- `POST /webhooks/{id}/rotate_secret` issues a new secret; the old one keeps signing alongside it for 24 hours.
- Corrections have no events; use `GET /corrections/{id}?wait=10`.

## Data model and consistency

- **Merges:** duplicate records are merged; old refs resolve to the survivor, which has `merged_from`. Store `id`, not the domain.
- **Removed records:** a suppressed or deleted record returns `404`. Remove it on your side.
- **Unknown versus zero:** `null` is unknown. A missing `total_funding_usd` is not zero, and a company without rounds may still have a funding total.
- **Freshness:** `refreshed_at` is when our serving copy was rebuilt. It does not mean a value changed.
- **Funding:** totals, rounds and investor links are independent measures; a total can exist without accepted rounds. Only accepted, non-superseded rounds and exits are returned.
- **Pages are live; exports are a single consistent read** taken when the export runs (a `search_id` export keeps its ranking's membership and order).
- **Sources:** `expand: ["sources"]` shows evidence for specific fields. Treat unsourced fields as StartupSeeker's best current value.

## Using with AI agents

- **MCP:** connect Claude, ChatGPT or Cursor to `https://startup-seeker.com/mcp/v4` and sign in with OAuth ([setup](/connect/mcp)). The MCP tools use the same data, filters (this object form or the predicate form), quotas and balance as the REST API, and return compact CSV with a summary line. Paid steps return a quote that the person approves.
- **For your own agent over REST:** give it [/api/v4/docs.md](/api/v4/docs.md) (this guide plus an endpoint index, small enough for a context window), the per-endpoint pages linked from it, and [OpenAPI](/api/v4/openapi.json).
- **Good behaviour:** report `meta.applied_filter` when you narrow a question; say when a total is `exact: false` or a page was `shortened`; treat `null` as unknown; never present a semantic ranking or truncated relation as complete; ask before approving a quote above 0¢.

## Versioning and changelog

- The version is in the path (`/api/v4`). Within v4 we only add things: new endpoints, new optional parameters, new response fields and new error codes. Build clients that ignore unknown fields.
- Breaking changes get a new major version and at least 3 months of overlap. Retiring versions answer with `Deprecation` and `Sunset` headers.
- **v3** (`/api/v3`) is deprecated as of v4's release; it keeps working for at least 3 months after v4 general availability. **v2** ends on 2026-12-31.

### Changelog

- **2026-11-15: v4.0.0.** First release of v4: object filter grammar, cursor-only pagination with pages that fit, nested expand pages, `/match`, named aggregate columns, one job lifecycle with approval and `?wait`, `client_reference`, free idempotent replays, a typed error catalog, rate-limit headers, `/account`, and signed webhooks with subscriptions, rotation and a delivery log.

## Migrate from v3

| v3 | v4 |
| --- | --- |
| `POST /{collection}/search` with a predicate tree | same path; filter is an object: `{"field":"hq_country","op":"eq","value":"DE"}` → `{"hq_country":"DE"}` |
| `include` | `expand`; relations are nested page objects |
| `meta.truncated_includes` | `page` inside each expanded relation |
| `meta.next_cursor` + resending the query | `page.next_cursor`, sent alone |
| `meta.total_count` + `count_mode` | `page.total` `{value, exact}` |
| `result_set` | `meta.search_id` (for exports); cursors cover paging |
| `sort: [{"field":"x","dir":"desc"}]` | `sort: ["-x"]` |
| `POST /{collection}/batch-get`, `POST /resolve` | `POST /{collection}/match`; `GET /industries`, `GET /locations` |
| `GET /{collection}/{ref}/relations/{relation}` | `GET /{collection}/{id}/{relation}` |
| aggregate `group_0`, `metric_0` | named columns (`hq_country`, `count`, `sum_amount_usd` or your `as`) |
| `/enrichment-runs`, `mode`, `scopes`, policies | `/enrichments`, `check_only`, `update` with `freshness` |
| `.../start` | `.../approve` |
| statuses `quote_ready`, `completed`, `cancelled`, … | `awaiting_approval`, `succeeded`, `canceled` (see [Jobs](#jobs)) |
| `/claims` | `/corrections` (`pending` → `verifying` → `resolved`) |
| `/webhook-endpoints`, `X-StartupSeeker-Signature: sha256=…` | `/webhooks`, `StartupSeeker-Signature: t=…,v1=…`, event subscriptions |
| error `billed`, `path` | `retryable`, `param`, `doc_url`, `details` |
| `/schema` operators `contains_any`, `is_null` … | `any`, `exists` … |

The full v3 reference stays at [/api-docs/v3](/api-docs/v3) while v3 is supported.

## Recipes

### Search and page through results

Seed-stage fintechs in Germany, all pages.

1. Search with a filter, the fields you need and a sort.

   `POST /api/v4/startups/search`

   ```json
   {"filter":{"hq_country":"DE","industries":{"any":["fintech"]},"last_round_type":"seed"},"fields":["name","domain","last_round_at"],"sort":["-last_round_at"],"limit":100}
   ```

2. Repeat with only the cursor until page.next_cursor is null.

   `POST /api/v4/startups/search`

   ```json
   {"cursor":"<page.next_cursor>"}
   ```

### Open a record and its relations

An investor, its portfolio, and the rest of the portfolio.

1. Get the investor with its portfolio expanded (first 25).

   `GET /api/v4/investors/sequoiacap.com?fields=name,domain,portfolio_linked_count&expand=portfolio`

2. Continue the portfolio with the nested cursor.

   `GET /api/v4/investors/<data.id>/portfolio?cursor=<data.portfolio.page.next_cursor>&limit=100`

### Export a search to CSV

Quote, approve, wait, download.

1. Create the export with the same filter as a search.

   `POST /api/v4/exports`

   ```json
   {"collection":"startups","filter":{"hq_country":"BE","total_funding_usd":{"gte":1000000}},"fields":["name","domain","total_funding_usd"],"format":"csv","client_reference":"be-funded"}
   ```

2. Check quote.rows and quote.max_cost_usd_cents, then approve that quote.

   `POST /api/v4/exports/<data.id>/approve`

   ```json
   {"quote_id":"<data.quote.quote_id>"}
   ```

3. Wait until it succeeds, then download result.download_url (valid 5 minutes, renewed on every read).

   `GET /api/v4/exports/<data.id>?wait=10`

### Enrich your company list

Check a CSV, refresh funding, read results.

1. Create an enrichment from your CSV and choose what to refresh.

   `POST /api/v4/enrichments`

   ```json
   {"companies":{"csv":"website\nacme.com\nbeta.io"},"update":{"funding":{"freshness":"30d"}},"client_reference":"crm-sync-42"}
   ```

2. Wait for awaiting_approval and review quote.lines and quote.max_cost_usd_cents.

   `GET /api/v4/enrichments/<data.id>?wait=10`

3. Approve the quote (0¢ quotes start on their own).

   `POST /api/v4/enrichments/<data.id>/approve`

   ```json
   {"quote_id":"<data.quote.quote_id>"}
   ```

4. When it succeeds, read one row per company.

   `GET /api/v4/enrichments/<data.id>/results?limit=100`

### Size a market

Funding raised per country over the last 12 months.

1. Aggregate funding rounds by country.

   `POST /api/v4/funding_rounds/aggregate`

   ```json
   {"filter":{"announced_at":{"gte":"-12m"},"startup":{"some":{"industries":{"any":["group:climate"]}}}},"group_by":["hq_country"],"metrics":["count",{"sum":"amount_usd","as":"raised_usd"}],"sort":["-raised_usd"],"limit":20}
   ```

### Find look-alikes and match a list

Similar companies, and resolving names you have.

1. Rank look-alikes of a company.

   `POST /api/v4/startups/search`

   ```json
   {"similar_to":"northvolt.com","fields":["name","domain","hq_country"],"limit":25}
   ```

2. Match the names and domains you already have.

   `POST /api/v4/startups/match`

   ```json
   {"values":["Northvolt","altris.se","not-a-company.example"]}
   ```

## Endpoints

Each endpoint has a page with every parameter, response field, error and examples.

| Endpoint | What it does | Price | Details |
| --- | --- | --- | --- |
| `POST /api/v4/{collection}/search` | Find records with a filter, an explicit sort, or semantic ranking (startups). Pages shrink to fit 1 MB; continue by sending only page.next_cursor. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/search.md |
| `GET /api/v4/{collection}/{ref}` | One record by UUID, domain, slug or LinkedIn URL (funding rounds and exits: UUID). expand nests related records with their own pagination. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/get.md |
| `GET /api/v4/{collection}/{id}/{relation}` | Page through one relation of a record (e.g. a startup's funding_rounds or an investor's portfolio) by the parent's UUID. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/relation.md |
| `POST /api/v4/{collection}/match` | Up to 100 domains, UUIDs, LinkedIn URLs or names in one call. One result per input, in input order: exact, candidates, not_found or invalid. Names never become exact. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/match.md |
| `POST /api/v4/{collection}/aggregate` | Exact counts and metrics, optionally grouped by up to two fields (dates by year, quarter or month). Columns carry real names; the top 100 groups are returned. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/aggregate.md |
| `GET /api/v4/schema` | Fields, types, filter operators, sortable and groupable fields and expandable relations for every collection. Free and public; cache for an hour. | Free | https://startup-seeker.com/api/v4/docs/schema.md |
| `GET /api/v4/schema/{collection}` | The schema of one collection; add ?fields=a,b for just those fields. | Free | https://startup-seeker.com/api/v4/docs/schema_collection.md |
| `GET /api/v4/industries` | Industry slugs and names, and the industry groups ("group:climate") that expand to several slugs. Free and public. | Free | https://startup-seeker.com/api/v4/docs/industries.md |
| `GET /api/v4/locations` | Resolve a place name to the country, region, state or GeoNames city ids that filters use. Free. | Free | https://startup-seeker.com/api/v4/docs/locations.md |
| `GET /api/v4/account` | Available and reserved balance, daily quotas with usage and reset times, and enrichment spend limits. Free. | Free | https://startup-seeker.com/api/v4/docs/account.md |
| `GET /api/v4/linkedin` | The public text of a LinkedIn company or profile page. Calls an external provider: 2¢ per call. | 2¢ per successful request | https://startup-seeker.com/api/v4/docs/linkedin.md |
| `GET /api/v4/lists` | Your saved lists, default list first, then most recently active. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/list_lists.md |
| `POST /api/v4/lists` | Create a saved list. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/create_list.md |
| `GET /api/v4/lists/{id}` | A list with its item count. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/get_list.md |
| `PATCH /api/v4/lists/{id}` | Rename a list or change its description. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/update_list.md |
| `DELETE /api/v4/lists/{id}` | Delete a list and its items. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/delete_list.md |
| `GET /api/v4/lists/{id}/items` | Items in the order they were added, with name, HQ country and a short description. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/list_items.md |
| `POST /api/v4/lists/{id}/items` | Add up to 100 startups (UUIDs or domains). Items already on the list are counted, not duplicated. | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/add_items.md |
| `POST /api/v4/lists/{id}/items/remove` | Remove up to 100 startups (UUIDs or domains). | 1¢ per successful request | https://startup-seeker.com/api/v4/docs/remove_items.md |
| `POST /api/v4/exports` | Quote a CSV or JSONL file of a search (or of a semantic search by search_id). The job waits for approval; a 0¢ quote starts at once. | Free | https://startup-seeker.com/api/v4/docs/create_export.md |
| `GET /api/v4/exports` | Your exports, newest first; filter by client_reference. | Free | https://startup-seeker.com/api/v4/docs/list_exports.md |
| `GET /api/v4/exports/{id}` | Status, quote, cost and, once succeeded, a 5-minute download link (renewed on every read). ?wait=10 waits for a change. | Free | https://startup-seeker.com/api/v4/docs/get_export.md |
| `POST /api/v4/exports/{id}/approve` | Start the export at its quoted price. Reserves quote.max_cost_usd_cents; actual rows are charged. | Free | https://startup-seeker.com/api/v4/docs/approve_export.md |
| `POST /api/v4/exports/{id}/cancel` | Cancel an export; unspent reservations are refunded. | Free | https://startup-seeker.com/api/v4/docs/cancel_export.md |
| `POST /api/v4/enrichments` | Check up to 5,000 companies (free VC-backability check), then quote web updates of company details, funding or founders. A 0¢ quote starts on its own. | Free | https://startup-seeker.com/api/v4/docs/create_enrichment.md |
| `GET /api/v4/enrichments` | Your enrichment jobs, newest first; filter by client_reference. | Free | https://startup-seeker.com/api/v4/docs/list_enrichments.md |
| `GET /api/v4/enrichments/{id}` | Status, progress, quote and cost. ?wait=10 waits for a change. | Free | https://startup-seeker.com/api/v4/docs/get_enrichment.md |
| `PATCH /api/v4/enrichments/{id}` | Change update before approval. Returns a new quote without re-running the check. | Free | https://startup-seeker.com/api/v4/docs/configure_enrichment.md |
| `POST /api/v4/enrichments/{id}/approve` | Start the updates at the quoted price. Reserves quote.max_cost_usd_cents; only updates that succeed are charged. | Free | https://startup-seeker.com/api/v4/docs/approve_enrichment.md |
| `POST /api/v4/enrichments/{id}/cancel` | Cancel; work already running may finish and settle (status canceling). | Free | https://startup-seeker.com/api/v4/docs/cancel_enrichment.md |
| `GET /api/v4/enrichments/{id}/results` | One row per company: check outcome, the StartupSeeker record and what was updated. | Free | https://startup-seeker.com/api/v4/docs/enrichment_results.md |
| `POST /api/v4/corrections` | Propose a source-backed fix to a record. It is verified against the source; read it back for the decision. | Free | https://startup-seeker.com/api/v4/docs/create_correction.md |
| `GET /api/v4/corrections/{id}` | pending, verifying or resolved, with the decision and reason. ?wait=10 waits for a change. | Free | https://startup-seeker.com/api/v4/docs/get_correction.md |
| `GET /api/v4/webhooks` | Your webhook endpoints. | Free | https://startup-seeker.com/api/v4/docs/list_webhooks.md |
| `POST /api/v4/webhooks` | Register an HTTPS endpoint and the events it receives. The signing secret is returned once. | Free | https://startup-seeker.com/api/v4/docs/create_webhook.md |
| `GET /api/v4/webhooks/{id}` | One webhook endpoint. | Free | https://startup-seeker.com/api/v4/docs/get_webhook.md |
| `PATCH /api/v4/webhooks/{id}` | Change the URL, label or subscribed events. | Free | https://startup-seeker.com/api/v4/docs/update_webhook.md |
| `DELETE /api/v4/webhooks/{id}` | Stop deliveries to this endpoint. | Free | https://startup-seeker.com/api/v4/docs/delete_webhook.md |
| `POST /api/v4/webhooks/{id}/rotate_secret` | Issue a new secret. The previous one keeps signing (as a second v1) for 24 hours. | Free | https://startup-seeker.com/api/v4/docs/rotate_webhook_secret.md |
| `POST /api/v4/webhooks/{id}/test` | Queue a signed webhook.test event. | Free | https://startup-seeker.com/api/v4/docs/test_webhook.md |
| `GET /api/v4/webhooks/{id}/deliveries` | Deliveries of the last 30 days with status, attempts and the last response. | Free | https://startup-seeker.com/api/v4/docs/list_deliveries.md |
| `POST /api/v4/webhooks/{id}/deliveries/{delivery_id}/redeliver` | Send a delivery again now (one more attempt). | Free | https://startup-seeker.com/api/v4/docs/redeliver.md |

## Error codes

`COLUMN_NAME_CONFLICT` (400), `CURSOR_INVALID` (400), `OPERATOR_NOT_SUPPORTED` (400), `QUERY_TOO_COMPLEX` (400), `SEMANTIC_NOT_SUPPORTED` (400), `TAG_ARRAY_NEEDS_OPERATOR` (400), `UNKNOWN_FIELD` (400), `VALIDATION_FAILED` (400), `VALUE_AMBIGUOUS` (400), `VALUE_UNKNOWN` (400), `UNAUTHORIZED` (401), `INSUFFICIENT_FUNDS` (402), `FORBIDDEN` (403), `SPEND_LIMIT_EXCEEDED` (403), `NOT_FOUND` (404), `RECORD_REMOVED` (404), `METHOD_NOT_ALLOWED` (405), `CHECK_ONLY_JOB` (409), `CONFLICT` (409), `IDEMPOTENCY_IN_PROGRESS` (409), `IDEMPOTENCY_MISMATCH` (409), `JOB_NOT_CONFIGURABLE` (409), `PRICE_CHANGED` (409), `QUOTE_EXPIRED` (409), `QUOTE_NOT_READY` (409), `REF_AMBIGUOUS` (409), `CURSOR_EXPIRED` (410), `SEARCH_EXPIRED` (410), `BODY_TOO_LARGE` (413), `RECORD_TOO_LARGE` (413), `QUOTA_EXCEEDED` (429), `RATE_LIMITED` (429), `INTERNAL_ERROR` (500), `MUTATION_OUTCOME_UNKNOWN` (500), `SERVICE_UNAVAILABLE` (503), `QUERY_TIMEOUT` (504). Full catalog: https://startup-seeker.com/api/v4/docs/errors.md

## Fields

Per collection: https://startup-seeker.com/api/v4/docs/fields/startups.md · https://startup-seeker.com/api/v4/docs/fields/investors.md · https://startup-seeker.com/api/v4/docs/fields/funding_rounds.md · https://startup-seeker.com/api/v4/docs/fields/exits.md