# 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

## Endpoint reference

### POST /api/v4/{collection}/search

**Search records** (`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. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" | yes | startups, investors, funding_rounds or exits. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | object |  | v4 filter object. Sibling keys AND; see the Filters guide. |
| `query` | string |  | Startups only: rank by meaning (semantic search). Replaces sort. |
| `similar_to` | string |  | Startups only: rank look-alikes of this startup (domain or UUID). Replaces sort. |
| `sort` | array<string> |  | Up to three field names; prefix "-" for descending. NULL sorts last; id breaks ties. |
| `fields` | array<string> |  | Fields to return. Omit for the default fields. id is always returned. |
| `expand` | array<string> |  | Related records to nest, e.g. ["funding_rounds","investors"]. See /schema for per-record caps. |
| `focus` | object |  | Investors only: rank by sector specialisation, e.g. {"industries":["fintech"]}. Adds focus_count, focus_total, focus_share, focus_score. |
| `limit` | integer |  | Rows per page, 1–100 (default 25). Pages also shrink to fit 1 MB. |
| `cursor` | string |  | page.next_cursor from the previous page. Send only the cursor (and optionally limit) to continue. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | A record with the requested fields (see /schema). Expanded to-many relations are page objects {data, page}; to-one relations are objects or null. |
| `data[].id` | string | yes | UUID. |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |
| `meta.applied_filter` | object \| null | yes | The filter that ran, after normalisation, in v4 grammar. |
| `meta.search_id` | string \| null |  | Semantic searches: handle for POST /exports {search_id}; valid 30 minutes. |
| `meta.search_expires_at` | string |  | ISO 8601 timestamp (UTC). |
| `meta.ranking` | object |  | Semantic searches only. Ranking is approximate and never exhaustive. |
| `meta.ranking.type` | "semantic" | yes |  |
| `meta.ranking.coverage` | "within_filter" \| "post_filtered" \| null | yes | within_filter: every startup the filter allows was ranked. post_filtered: more than 10,000 startups matched, so ranking is approximate; strong matches can be missed. |
| `meta.ranking.population` | number \| null | yes | Startups the filter allows (when known). |
| `meta.ranking.ranked` | number \| null | yes | Candidates that were ranked. |
| `meta.ranking.unranked` | number \| null | yes | Allowed startups without a semantic profile, so not ranked. |
| `meta.ranking.dropped` | number | yes | Ranked rows on this page that no longer exist. |
| `meta.focus` | object |  | Investors with focus: the sectors and how focus_score ranks them. |
| `meta.diagnostics` | any |  | For empty results: which conditions removed the most records. |
| `meta.match_scope` | string |  | Investors: independent_firm_facets when stage, sector and geography are matched separately, not as one joint strategy. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. |
| 400 | `OPERATOR_NOT_SUPPORTED` | The operator is not available for this field. |
| 400 | `TAG_ARRAY_NEEDS_OPERATOR` | A bare array was given for a tag field. |
| 400 | `VALUE_UNKNOWN` | A filter value does not match any known value. |
| 400 | `VALUE_AMBIGUOUS` | A friendly filter value matches several canonical values. |
| 400 | `QUERY_TOO_COMPLEX` | The filter exceeds the complexity limits. |
| 400 | `SEMANTIC_NOT_SUPPORTED` | Semantic ranking (query / similar_to) is only available for startups. |
| 400 | `CURSOR_INVALID` | The cursor is malformed, belongs to another query or another account. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 410 | `CURSOR_EXPIRED` | The cursor expired (24 h, or 30 min for semantic rankings). |
| 413 | `RECORD_TOO_LARGE` | A single record exceeds the 1 MB response budget. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |
| 504 | `QUERY_TIMEOUT` | The query ran out of its time budget. |

#### Example

```bash

curl -X POST '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"
        ]
      },
      "total_funding_usd": {
        "gte": 1000000
      }
    },
    "fields": [
      "name",
      "domain",
      "total_funding_usd"
    ],
    "sort": [
      "-total_funding_usd"
    ],
    "limit": 2
  }'

```

### GET /api/v4/{collection}/{ref}

**Get a record** (`get`). 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. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" | yes | startups, investors, funding_rounds or exits. |
| `ref` | string | yes | UUID, domain, slug or LinkedIn URL (percent-encode URLs). |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | array<string> (comma-separated) |  |  |
| `expand` | array<string> (comma-separated) |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | A record with the requested fields (see /schema). Expanded to-many relations are page objects {data, page}; to-one relations are objects or null. |
| `data.id` | string | yes | UUID. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `REF_AMBIGUOUS` | The ref matches several records. |
| 413 | `RECORD_TOO_LARGE` | A single record exceeds the 1 MB response budget. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |
| 504 | `QUERY_TIMEOUT` | The query ran out of its time budget. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/startups/stripe.com?fields=name,domain,total_funding_usd&expand=funding_rounds' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### GET /api/v4/{collection}/{id}/{relation}

**List related records** (`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. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" | yes | startups, investors, funding_rounds or exits. |
| `id` | string | yes | Parent record UUID. |
| `relation` | string | yes | A to-many relation listed under expand in /schema. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | array<string> (comma-separated) |  |  |
| `limit` | integer |  |  |
| `cursor` | string |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 400 | `CURSOR_INVALID` | The cursor is malformed, belongs to another query or another account. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 410 | `CURSOR_EXPIRED` | The cursor expired (24 h, or 30 min for semantic rankings). |
| 413 | `RECORD_TOO_LARGE` | A single record exceeds the 1 MB response budget. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |
| 504 | `QUERY_TIMEOUT` | The query ran out of its time budget. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/investors/11111111-1111-4111-8111-111111111111/portfolio?limit=50' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### POST /api/v4/{collection}/match

**Match refs and names** (`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. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" | yes | startups, investors, funding_rounds or exits. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `values` | array<string> | yes | Domains, UUIDs, slugs, LinkedIn URLs or names (names: startups and investors only). |
| `fields` | array<string> |  | Fields for exact matches. Omit for the default fields. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].input` | string | yes |  |
| `data[].status` | "exact" \| "candidates" \| "not_found" \| "invalid" | yes |  |
| `data[].record` | object |  | For exact matches. |
| `data[].record.id` | string | yes | UUID. |
| `data[].candidates` | array<object> |  |  |
| `data[].candidates[].id` | string | yes | UUID. |
| `data[].candidates[].name` | string \| null |  |  |
| `data[].candidates[].domain` | string \| null |  |  |
| `data[].candidates[].confidence` | number \| null |  |  |
| `data[].error` | object |  |  |
| `data[].error.code` | string | yes |  |
| `data[].error.message` | string | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/startups/match' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      "stripe.com",
      "Mistral AI"
    ],
    "fields": [
      "name",
      "domain"
    ]
  }'

```

### POST /api/v4/{collection}/aggregate

**Count and summarise** (`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. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" | yes | startups, investors, funding_rounds or exits. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | object |  |  |
| `group_by` | array<string \| object> |  | Up to two fields; dates as {"field":"announced_at","bucket":"quarter"}. Funding rounds can group by "investor"; exits by "acquirer". |
| `metrics` | array<"count" \| object> |  | Default ["count"]. Others: {"sum":"amount_usd"}, {"avg":…}, {"min":…}, {"max":…}, {"count_distinct":…}; add "as" to name the column. |
| `sort` | array<string> |  | Output column names; "-" for descending. Default: first metric descending. |
| `limit` | integer |  | Top groups to return, 1–100 (default 100). |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |
| `meta.applied_filter` | object \| null | yes |  |
| `meta.records` | object | yes | Records matching the filter. |
| `meta.records.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `meta.records.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `meta.groups` | object | yes | Aggregates return the top groups; complete is false when groups were left out. |
| `meta.groups.returned` | integer | yes |  |
| `meta.groups.total` | integer | yes |  |
| `meta.groups.complete` | boolean | yes |  |
| `meta.groups_overlap` | boolean |  | true for tag or investor groupings: a record can be in several groups, so sums are not additive. |
| `meta.totals` | object |  | count and sum across all matching records (scalar groupings only). |
| `meta.match_scope` | string |  |  |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. |
| 400 | `OPERATOR_NOT_SUPPORTED` | The operator is not available for this field. |
| 400 | `VALUE_UNKNOWN` | A filter value does not match any known value. |
| 400 | `VALUE_AMBIGUOUS` | A friendly filter value matches several canonical values. |
| 400 | `QUERY_TOO_COMPLEX` | The filter exceeds the complexity limits. |
| 400 | `COLUMN_NAME_CONFLICT` | Two aggregate columns would have the same name. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |
| 504 | `QUERY_TIMEOUT` | The query ran out of its time budget. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/funding_rounds/aggregate' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "announced_at": {
        "gte": "-12m"
      }
    },
    "group_by": [
      "hq_country"
    ],
    "metrics": [
      "count",
      {
        "sum": "amount_usd",
        "as": "raised_usd"
      }
    ],
    "sort": [
      "-raised_usd"
    ],
    "limit": 5
  }'

```

### GET /api/v4/schema

**Schema** (`schema`). Fields, types, filter operators, sortable and groupable fields and expandable relations for every collection. Free and public; cache for an hour.

Free. Public. Success: `200`.

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/schema'

```

### GET /api/v4/schema/{collection}

**Schema for one collection** (`schema_collection`). The schema of one collection; add ?fields=a,b for just those fields.

Free. Public. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" | yes | startups, investors, funding_rounds or exits. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | array<string> (comma-separated) |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/schema/investors?fields=stages,check_size_typ_usd'

```

### GET /api/v4/industries

**Industries** (`industries`). Industry slugs and names, and the industry groups ("group:climate") that expand to several slugs. Free and public.

Free. Public. Success: `200`.

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].slug` | string | yes |  |
| `data[].name` | string | yes |  |
| `data[].groups` | array<string> | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |
| `meta.groups` | array<object> | yes |  |
| `meta.groups[].name` | string | yes |  |
| `meta.groups[].industries` | array<string> | yes |  |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/industries'

```

### GET /api/v4/locations

**Find locations** (`locations`). Resolve a place name to the country, region, state or GeoNames city ids that filters use. Free.

Free. API key required. Success: `200`.

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | yes |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/locations?q=Munich' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### GET /api/v4/account

**Account balance and quotas** (`account`). Available and reserved balance, daily quotas with usage and reset times, and enrichment spend limits. Free.

Free. API key required. Success: `200`.

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.balance` | object | yes |  |
| `data.balance.available_usd_cents` | integer | yes | USD cents. |
| `data.balance.reserved_usd_cents` | integer | yes | USD cents. |
| `data.quotas` | object | yes |  |
| `data.note` | string | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/account' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### GET /api/v4/linkedin

**Read a LinkedIn page** (`linkedin`). The public text of a LinkedIn company or profile page. Calls an external provider: 2¢ per call.

2¢ per successful request. API key required. Success: `200`.

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.url` | string | yes |  |
| `data.kind` | "company" \| "profile" | yes |  |
| `data.text` | string | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/linkedin?url=https://www.linkedin.com/company/stripe' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### GET /api/v4/lists

**List saved lists** (`list_lists`). Your saved lists, default list first, then most recently active.

1¢ per successful request. API key required. Success: `200`.

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer |  |  |
| `cursor` | string |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].id` | string | yes | UUID. |
| `data[].name` | string | yes |  |
| `data[].description` | string \| null | yes |  |
| `data[].is_default` | boolean | yes |  |
| `data[].item_count` | integer \| null | yes |  |
| `data[].created_at` | string \| null | yes |  |
| `data[].updated_at` | string \| null | yes |  |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/lists' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### POST /api/v4/lists

**Create a list** (`create_list`). Create a saved list.

1¢ per successful request. API key required. Success: `201`. Accepts `Idempotency-Key`.

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `description` | string \| null |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.name` | string | yes |  |
| `data.description` | string \| null | yes |  |
| `data.is_default` | boolean | yes |  |
| `data.item_count` | integer \| null | yes |  |
| `data.created_at` | string \| null | yes |  |
| `data.updated_at` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/lists' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Berlin fintech",
    "description": "Seed to Series A"
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### GET /api/v4/lists/{id}

**Get a list** (`get_list`). A list with its item count.

1¢ per successful request. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | List UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.name` | string | yes |  |
| `data.description` | string \| null | yes |  |
| `data.is_default` | boolean | yes |  |
| `data.item_count` | integer \| null | yes |  |
| `data.created_at` | string \| null | yes |  |
| `data.updated_at` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/lists/<id>' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### PATCH /api/v4/lists/{id}

**Update a list** (`update_list`). Rename a list or change its description.

1¢ per successful request. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | List UUID. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string |  |  |
| `description` | string \| null |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.name` | string | yes |  |
| `data.description` | string \| null | yes |  |
| `data.is_default` | boolean | yes |  |
| `data.item_count` | integer \| null | yes |  |
| `data.created_at` | string \| null | yes |  |
| `data.updated_at` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X PATCH 'https://startup-seeker.com/api/v4/lists/11111111-1111-4111-8111-111111111111' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Berlin fintech 2026"
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### DELETE /api/v4/lists/{id}

**Delete a list** (`delete_list`). Delete a list and its items.

1¢ per successful request. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | List UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.deleted` | true | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X DELETE 'https://startup-seeker.com/api/v4/lists/<id>' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

```

### GET /api/v4/lists/{id}/items

**List items** (`list_items`). Items in the order they were added, with name, HQ country and a short description.

1¢ per successful request. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | List UUID. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer |  |  |
| `cursor` | string |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].id` | string | yes | UUID. |
| `data[].startup_id` | string \| null | yes |  |
| `data[].domain` | string | yes |  |
| `data[].name` | string \| null | yes |  |
| `data[].hq_country` | string \| null | yes |  |
| `data[].description` | string \| null | yes |  |
| `data[].added_at` | string | yes | ISO 8601 timestamp (UTC). |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/lists/<id>/items' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### POST /api/v4/lists/{id}/items

**Add items** (`add_items`). Add up to 100 startups (UUIDs or domains). Items already on the list are counted, not duplicated.

1¢ per successful request. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | List UUID. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<string> | yes | Startup UUIDs or domains. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.list_id` | string | yes | UUID. |
| `data.added` | integer | yes |  |
| `data.already_present` | integer | yes |  |
| `data.item_count` | integer | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/lists/11111111-1111-4111-8111-111111111111/items' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      "stripe.com",
      "mistral.ai"
    ]
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### POST /api/v4/lists/{id}/items/remove

**Remove items** (`remove_items`). Remove up to 100 startups (UUIDs or domains).

1¢ per successful request. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | List UUID. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<string> | yes | Startup UUIDs or domains. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.list_id` | string | yes | UUID. |
| `data.removed` | integer | yes |  |
| `data.item_count` | integer | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/lists/11111111-1111-4111-8111-111111111111/items/remove' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      "stripe.com"
    ]
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### POST /api/v4/exports

**Create an export** (`create_export`). 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. API key required. Success: `202`. Accepts `Idempotency-Key`.

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" |  |  |
| `search_id` | string |  | meta.search_id of a semantic search: exports exactly that ranking, with its filter, fields and expands. |
| `filter` | object |  |  |
| `sort` | array<string> |  |  |
| `fields` | array<string> |  |  |
| `expand` | array<string> |  |  |
| `focus` | object |  |  |
| `format` | "csv" \| "jsonl" | yes |  |
| `client_reference` | string |  | Your own reference (≤200 chars). Filter job lists by it to find work again. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "export" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string \| null | yes |  |
| `data.finished_at` | string \| null | yes |  |
| `data.collection` | any | yes |  |
| `data.format` | any | yes |  |
| `data.quote` | object | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.rows` | integer | yes |  |
| `data.quote.max_cost_usd_cents` | integer | yes | The most approval can charge. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.lines` | array<object> | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.rows` | integer | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.result` | object \| null | yes |  |
| `data.result.download_url` | string \| null | yes |  |
| `data.result.url_expires_at` | string \| null |  |  |
| `data.result.artifact_expires_at` | string \| null | yes |  |
| `data.result.filename` | string |  |  |
| `data.result.rows` | integer | yes |  |
| `data.result.truncated_to_quote` | boolean |  |  |
| `data.result.note` | string |  |  |
| `data.failure` | object \| null | yes |  |
| `data.failure.code` | string | yes |  |
| `data.failure.message` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. |
| 400 | `VALUE_UNKNOWN` | A filter value does not match any known value. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 410 | `SEARCH_EXPIRED` | The ranked search (search_id) expired after 30 minutes. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/exports' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "startups",
    "filter": {
      "hq_country": "BE"
    },
    "fields": [
      "name",
      "domain",
      "total_funding_usd"
    ],
    "format": "csv",
    "client_reference": "be-startups"
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### GET /api/v4/exports

**List exports** (`list_exports`). Your exports, newest first; filter by client_reference.

Free. API key required. Success: `200`.

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer |  |  |
| `cursor` | string |  |  |
| `client_reference` | string |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].id` | string | yes | UUID. |
| `data[].type` | "export" | yes |  |
| `data[].status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data[].client_reference` | string \| null | yes |  |
| `data[].created_at` | string \| null | yes |  |
| `data[].finished_at` | string \| null | yes |  |
| `data[].collection` | any | yes |  |
| `data[].format` | any | yes |  |
| `data[].quote` | object | yes |  |
| `data[].quote.quote_id` | string | yes | UUID. |
| `data[].quote.rows` | integer | yes |  |
| `data[].quote.max_cost_usd_cents` | integer | yes | The most approval can charge. |
| `data[].quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data[].quote.lines` | array<object> | yes |  |
| `data[].progress` | object | yes |  |
| `data[].progress.rows` | integer | yes |  |
| `data[].cost` | object | yes |  |
| `data[].cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data[].cost.charged_usd_cents` | integer | yes | USD cents. |
| `data[].cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data[].result` | object \| null | yes |  |
| `data[].result.download_url` | string \| null | yes |  |
| `data[].result.url_expires_at` | string \| null |  |  |
| `data[].result.artifact_expires_at` | string \| null | yes |  |
| `data[].result.filename` | string |  |  |
| `data[].result.rows` | integer | yes |  |
| `data[].result.truncated_to_quote` | boolean |  |  |
| `data[].result.note` | string |  |  |
| `data[].failure` | object \| null | yes |  |
| `data[].failure.code` | string | yes |  |
| `data[].failure.message` | string \| null | yes |  |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/exports' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### GET /api/v4/exports/{id}

**Get an export** (`get_export`). Status, quote, cost and, once succeeded, a 5-minute download link (renewed on every read). ?wait=10 waits for a change.

Free. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Export UUID. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `wait` | integer |  | Seconds to wait (0–10) for the status to change before answering. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "export" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string \| null | yes |  |
| `data.finished_at` | string \| null | yes |  |
| `data.collection` | any | yes |  |
| `data.format` | any | yes |  |
| `data.quote` | object | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.rows` | integer | yes |  |
| `data.quote.max_cost_usd_cents` | integer | yes | The most approval can charge. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.lines` | array<object> | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.rows` | integer | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.result` | object \| null | yes |  |
| `data.result.download_url` | string \| null | yes |  |
| `data.result.url_expires_at` | string \| null |  |  |
| `data.result.artifact_expires_at` | string \| null | yes |  |
| `data.result.filename` | string |  |  |
| `data.result.rows` | integer | yes |  |
| `data.result.truncated_to_quote` | boolean |  |  |
| `data.result.note` | string |  |  |
| `data.failure` | object \| null | yes |  |
| `data.failure.code` | string | yes |  |
| `data.failure.message` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/exports/<id>' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### POST /api/v4/exports/{id}/approve

**Approve an export** (`approve_export`). Start the export at its quoted price. Reserves quote.max_cost_usd_cents; actual rows are charged.

Free. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Export UUID. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `quote_id` | string | yes | The quote_id you are approving. A stale id returns 409 QUOTE_EXPIRED with the new quote. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "export" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string \| null | yes |  |
| `data.finished_at` | string \| null | yes |  |
| `data.collection` | any | yes |  |
| `data.format` | any | yes |  |
| `data.quote` | object | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.rows` | integer | yes |  |
| `data.quote.max_cost_usd_cents` | integer | yes | The most approval can charge. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.lines` | array<object> | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.rows` | integer | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.result` | object \| null | yes |  |
| `data.result.download_url` | string \| null | yes |  |
| `data.result.url_expires_at` | string \| null |  |  |
| `data.result.artifact_expires_at` | string \| null | yes |  |
| `data.result.filename` | string |  |  |
| `data.result.rows` | integer | yes |  |
| `data.result.truncated_to_quote` | boolean |  |  |
| `data.result.note` | string |  |  |
| `data.failure` | object \| null | yes |  |
| `data.failure.code` | string | yes |  |
| `data.failure.message` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `QUOTE_EXPIRED` | The quote is older than 30 minutes or was replaced. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/exports/11111111-1111-4111-8111-111111111111/approve' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "22222222-2222-4222-8222-222222222222"
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### POST /api/v4/exports/{id}/cancel

**Cancel an export** (`cancel_export`). Cancel an export; unspent reservations are refunded.

Free. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Export UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "export" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string \| null | yes |  |
| `data.finished_at` | string \| null | yes |  |
| `data.collection` | any | yes |  |
| `data.format` | any | yes |  |
| `data.quote` | object | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.rows` | integer | yes |  |
| `data.quote.max_cost_usd_cents` | integer | yes | The most approval can charge. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.lines` | array<object> | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.rows` | integer | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.result` | object \| null | yes |  |
| `data.result.download_url` | string \| null | yes |  |
| `data.result.url_expires_at` | string \| null |  |  |
| `data.result.artifact_expires_at` | string \| null | yes |  |
| `data.result.filename` | string |  |  |
| `data.result.rows` | integer | yes |  |
| `data.result.truncated_to_quote` | boolean |  |  |
| `data.result.note` | string |  |  |
| `data.failure` | object \| null | yes |  |
| `data.failure.code` | string | yes |  |
| `data.failure.message` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/exports/<id>/cancel' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

```

### POST /api/v4/enrichments

**Create an enrichment** (`create_enrichment`). 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. API key required. Success: `202`. Accepts `Idempotency-Key`.

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `companies` | array<string> \| object | yes | Domains (≤5,000), {"list_id": …} or {"csv": "…"} with a website/domain/url column. |
| `companies.list_id` | string | yes |  |
| `check_only` | boolean |  | Run only the free VC-backability check. The job succeeds after the check and has no quote. |
| `update` | object |  | Which data to refresh from the web. true = refresh data older than 6 months; {"freshness":"12m"\|"6m"\|"30d"\|"always"}; false or omitted = keep StartupSeeker data. |
| `update.details` | boolean \| object |  |  |
| `update.funding` | boolean \| object |  |  |
| `update.founders` | boolean \| object |  |  |
| `client_reference` | string |  | Your own reference (≤200 chars). Filter job lists by it to find work again. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "enrichment" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.check_only` | boolean | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.finished_at` | string \| null | yes |  |
| `data.update` | object \| null | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.companies` | integer | yes |  |
| `data.progress.checked` | integer | yes |  |
| `data.progress.vc_backable` | integer | yes |  |
| `data.progress.ready` | integer | yes |  |
| `data.progress.issues` | integer | yes |  |
| `data.quote` | object \| null | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.max_cost_usd_cents` | integer | yes | USD cents. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.new_companies` | integer | yes |  |
| `data.quote.lines` | array<object> | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.failure` | object \| null | yes |  |
| `data.failure.stage` | "check" \| "run" | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 403 | `FORBIDDEN` | This key or application may not perform the operation. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/enrichments' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": [
      "acme.com",
      "beta.io"
    ],
    "update": {
      "funding": {
        "freshness": "30d"
      }
    },
    "client_reference": "crm-sync-42"
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### GET /api/v4/enrichments

**List enrichments** (`list_enrichments`). Your enrichment jobs, newest first; filter by client_reference.

Free. API key required. Success: `200`.

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer |  |  |
| `cursor` | string |  |  |
| `client_reference` | string |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].id` | string | yes | UUID. |
| `data[].type` | "enrichment" | yes |  |
| `data[].status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data[].check_only` | boolean | yes |  |
| `data[].client_reference` | string \| null | yes |  |
| `data[].created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data[].finished_at` | string \| null | yes |  |
| `data[].update` | object \| null | yes |  |
| `data[].progress` | object | yes |  |
| `data[].progress.companies` | integer | yes |  |
| `data[].progress.checked` | integer | yes |  |
| `data[].progress.vc_backable` | integer | yes |  |
| `data[].progress.ready` | integer | yes |  |
| `data[].progress.issues` | integer | yes |  |
| `data[].quote` | object \| null | yes |  |
| `data[].quote.quote_id` | string | yes | UUID. |
| `data[].quote.max_cost_usd_cents` | integer | yes | USD cents. |
| `data[].quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data[].quote.new_companies` | integer | yes |  |
| `data[].quote.lines` | array<object> | yes |  |
| `data[].cost` | object | yes |  |
| `data[].cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data[].cost.charged_usd_cents` | integer | yes | USD cents. |
| `data[].cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data[].failure` | object \| null | yes |  |
| `data[].failure.stage` | "check" \| "run" | yes |  |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/enrichments' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### GET /api/v4/enrichments/{id}

**Get an enrichment** (`get_enrichment`). Status, progress, quote and cost. ?wait=10 waits for a change.

Free. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Enrichment UUID. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `wait` | integer |  | Seconds to wait (0–10) for the status to change before answering. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "enrichment" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.check_only` | boolean | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.finished_at` | string \| null | yes |  |
| `data.update` | object \| null | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.companies` | integer | yes |  |
| `data.progress.checked` | integer | yes |  |
| `data.progress.vc_backable` | integer | yes |  |
| `data.progress.ready` | integer | yes |  |
| `data.progress.issues` | integer | yes |  |
| `data.quote` | object \| null | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.max_cost_usd_cents` | integer | yes | USD cents. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.new_companies` | integer | yes |  |
| `data.quote.lines` | array<object> | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.failure` | object \| null | yes |  |
| `data.failure.stage` | "check" \| "run" | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/enrichments/<id>' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### PATCH /api/v4/enrichments/{id}

**Change what to update** (`configure_enrichment`). Change update before approval. Returns a new quote without re-running the check.

Free. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Enrichment UUID. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `update` | object | yes | Which data to refresh from the web. true = refresh data older than 6 months; {"freshness":"12m"\|"6m"\|"30d"\|"always"}; false or omitted = keep StartupSeeker data. |
| `update.details` | boolean \| object |  |  |
| `update.funding` | boolean \| object |  |  |
| `update.founders` | boolean \| object |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "enrichment" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.check_only` | boolean | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.finished_at` | string \| null | yes |  |
| `data.update` | object \| null | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.companies` | integer | yes |  |
| `data.progress.checked` | integer | yes |  |
| `data.progress.vc_backable` | integer | yes |  |
| `data.progress.ready` | integer | yes |  |
| `data.progress.issues` | integer | yes |  |
| `data.quote` | object \| null | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.max_cost_usd_cents` | integer | yes | USD cents. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.new_companies` | integer | yes |  |
| `data.quote.lines` | array<object> | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.failure` | object \| null | yes |  |
| `data.failure.stage` | "check" \| "run" | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `JOB_NOT_CONFIGURABLE` | The job can no longer be reconfigured. |
| 409 | `CHECK_ONLY_JOB` | A check-only enrichment has nothing to approve or configure. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X PATCH 'https://startup-seeker.com/api/v4/enrichments/11111111-1111-4111-8111-111111111111' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "update": {
      "details": true,
      "funding": {
        "freshness": "always"
      }
    }
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### POST /api/v4/enrichments/{id}/approve

**Approve an enrichment** (`approve_enrichment`). Start the updates at the quoted price. Reserves quote.max_cost_usd_cents; only updates that succeed are charged.

Free. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Enrichment UUID. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `quote_id` | string | yes | The quote_id you are approving. A stale id returns 409 QUOTE_EXPIRED with the new quote. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "enrichment" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.check_only` | boolean | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.finished_at` | string \| null | yes |  |
| `data.update` | object \| null | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.companies` | integer | yes |  |
| `data.progress.checked` | integer | yes |  |
| `data.progress.vc_backable` | integer | yes |  |
| `data.progress.ready` | integer | yes |  |
| `data.progress.issues` | integer | yes |  |
| `data.quote` | object \| null | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.max_cost_usd_cents` | integer | yes | USD cents. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.new_companies` | integer | yes |  |
| `data.quote.lines` | array<object> | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.failure` | object \| null | yes |  |
| `data.failure.stage` | "check" \| "run" | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 403 | `SPEND_LIMIT_EXCEEDED` | A per-job or daily enrichment spend limit would be exceeded. |
| 403 | `FORBIDDEN` | This key or application may not perform the operation. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `QUOTE_EXPIRED` | The quote is older than 30 minutes or was replaced. |
| 409 | `PRICE_CHANGED` | The price rose since the quote was issued. |
| 409 | `QUOTE_NOT_READY` | The job is still quoting. |
| 409 | `CHECK_ONLY_JOB` | A check-only enrichment has nothing to approve or configure. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/enrichments/11111111-1111-4111-8111-111111111111/approve' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "22222222-2222-4222-8222-222222222222"
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### POST /api/v4/enrichments/{id}/cancel

**Cancel an enrichment** (`cancel_enrichment`). Cancel; work already running may finish and settle (status canceling).

Free. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Enrichment UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.type` | "enrichment" | yes |  |
| `data.status` | "quoting" \| "awaiting_approval" \| "queued" \| "running" \| "canceling" \| "succeeded" \| "partially_succeeded" \| "failed" \| "canceled" | yes |  |
| `data.check_only` | boolean | yes |  |
| `data.client_reference` | string \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.finished_at` | string \| null | yes |  |
| `data.update` | object \| null | yes |  |
| `data.progress` | object | yes |  |
| `data.progress.companies` | integer | yes |  |
| `data.progress.checked` | integer | yes |  |
| `data.progress.vc_backable` | integer | yes |  |
| `data.progress.ready` | integer | yes |  |
| `data.progress.issues` | integer | yes |  |
| `data.quote` | object \| null | yes |  |
| `data.quote.quote_id` | string | yes | UUID. |
| `data.quote.max_cost_usd_cents` | integer | yes | USD cents. |
| `data.quote.expires_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.quote.new_companies` | integer | yes |  |
| `data.quote.lines` | array<object> | yes |  |
| `data.cost` | object | yes |  |
| `data.cost.reserved_usd_cents` | integer | yes | USD cents. |
| `data.cost.charged_usd_cents` | integer | yes | USD cents. |
| `data.cost.refunded_usd_cents` | integer | yes | USD cents. |
| `data.failure` | object \| null | yes |  |
| `data.failure.stage` | "check" \| "run" | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/enrichments/<id>/cancel' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

```

### GET /api/v4/enrichments/{id}/results

**Enrichment results** (`enrichment_results`). One row per company: check outcome, the StartupSeeker record and what was updated.

Free. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Enrichment UUID. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer |  |  |
| `cursor` | string |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].domain` | string | yes |  |
| `data[].outcome` | "checking" \| "vc_backable" \| "unresolved" \| "not_vc_backable" \| "failed" | yes |  |
| `data[].vc_backable` | boolean \| null | yes |  |
| `data[].name` | string \| null | yes |  |
| `data[].description` | string \| null | yes |  |
| `data[].company` | object \| null | yes | A record with the requested fields (see /schema). Expanded to-many relations are page objects {data, page}; to-one relations are objects or null. |
| `data[].company.id` | string | yes | UUID. |
| `data[].updates` | object | yes |  |
| `data[].failures` | array<string> | yes |  |
| `data[].message` | string \| null | yes |  |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/enrichments/<id>/results' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### POST /api/v4/corrections

**Submit a correction** (`create_correction`). Propose a source-backed fix to a record. It is verified against the source; read it back for the decision.

Free. API key required. Success: `202`. Accepts `Idempotency-Key`.

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.status` | "pending" \| "verifying" \| "resolved" | yes |  |
| `data.decision` | "approved" \| "rejected" \| "no_change" \| null | yes |  |
| `data.reason` | string \| null | yes |  |
| `data.explanation` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 403 | `FORBIDDEN` | This key or application may not perform the operation. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/corrections' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "stripe.com",
    "field": "founded_year",
    "value": 2010,
    "source_url": "https://stripe.com/about"
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### GET /api/v4/corrections/{id}

**Get a correction** (`get_correction`). pending, verifying or resolved, with the decision and reason. ?wait=10 waits for a change.

Free. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Correction UUID. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `wait` | integer |  | Seconds to wait (0–10) for the status to change before answering. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.status` | "pending" \| "verifying" \| "resolved" | yes |  |
| `data.decision` | "approved" \| "rejected" \| "no_change" \| null | yes |  |
| `data.reason` | string \| null | yes |  |
| `data.explanation` | string \| null | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/corrections/<id>' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### GET /api/v4/webhooks

**List webhooks** (`list_webhooks`). Your webhook endpoints.

Free. API key required. Success: `200`.

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].id` | string | yes | UUID. |
| `data[].url` | string \| null | yes |  |
| `data[].label` | string \| null | yes |  |
| `data[].api_version` | "v3" \| "v4" | yes |  |
| `data[].events` | array<string> \| null | yes |  |
| `data[].created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data[].updated_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data[].signing_secret` | string |  | Returned on create and rotate only. |
| `data[].previous_secret_valid_until` | string \| null |  |  |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/webhooks' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### POST /api/v4/webhooks

**Create a webhook** (`create_webhook`). Register an HTTPS endpoint and the events it receives. The signing secret is returned once.

Free. API key required. Success: `201`. Accepts `Idempotency-Key`.

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | Public HTTPS URL that receives POSTed events. |
| `label` | string \| null |  |  |
| `events` | array<string> |  | Event types to receive (default ["*"]). |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.url` | string \| null | yes |  |
| `data.label` | string \| null | yes |  |
| `data.api_version` | "v3" \| "v4" | yes |  |
| `data.events` | array<string> \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.updated_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.signing_secret` | string |  | Returned on create and rotate only. |
| `data.previous_secret_valid_until` | string \| null |  |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST '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"
    ]
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### GET /api/v4/webhooks/{id}

**Get a webhook** (`get_webhook`). One webhook endpoint.

Free. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Webhook UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.url` | string \| null | yes |  |
| `data.label` | string \| null | yes |  |
| `data.api_version` | "v3" \| "v4" | yes |  |
| `data.events` | array<string> \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.updated_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.signing_secret` | string |  | Returned on create and rotate only. |
| `data.previous_secret_valid_until` | string \| null |  |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/webhooks/<id>' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### PATCH /api/v4/webhooks/{id}

**Update a webhook** (`update_webhook`). Change the URL, label or subscribed events.

Free. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Webhook UUID. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string |  |  |
| `label` | string \| null |  |  |
| `events` | array<string> |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.url` | string \| null | yes |  |
| `data.label` | string \| null | yes |  |
| `data.api_version` | "v3" \| "v4" | yes |  |
| `data.events` | array<string> \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.updated_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.signing_secret` | string |  | Returned on create and rotate only. |
| `data.previous_secret_valid_until` | string \| null |  |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X PATCH 'https://startup-seeker.com/api/v4/webhooks/11111111-1111-4111-8111-111111111111' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "*"
    ]
  }' \
  -H "Idempotency-Key: $(uuidgen)"

```

### DELETE /api/v4/webhooks/{id}

**Delete a webhook** (`delete_webhook`). Stop deliveries to this endpoint.

Free. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Webhook UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.deleted` | true | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X DELETE 'https://startup-seeker.com/api/v4/webhooks/<id>' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

```

### POST /api/v4/webhooks/{id}/rotate_secret

**Rotate the signing secret** (`rotate_webhook_secret`). Issue a new secret. The previous one keeps signing (as a second v1) for 24 hours.

Free. API key required. Success: `200`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Webhook UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.url` | string \| null | yes |  |
| `data.label` | string \| null | yes |  |
| `data.api_version` | "v3" \| "v4" | yes |  |
| `data.events` | array<string> \| null | yes |  |
| `data.created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.updated_at` | string | yes | ISO 8601 timestamp (UTC). |
| `data.signing_secret` | string |  | Returned on create and rotate only. |
| `data.previous_secret_valid_until` | string \| null |  |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/webhooks/<id>/rotate_secret' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

```

### POST /api/v4/webhooks/{id}/test

**Send a test event** (`test_webhook`). Queue a signed webhook.test event.

Free. API key required. Success: `202`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Webhook UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.event_id` | string | yes |  |
| `data.delivery_id` | string | yes | UUID. |
| `data.status` | "pending" | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/webhooks/<id>/test' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

```

### GET /api/v4/webhooks/{id}/deliveries

**List deliveries** (`list_deliveries`). Deliveries of the last 30 days with status, attempts and the last response.

Free. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Webhook UUID. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer |  |  |
| `cursor` | string |  |  |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `data[].id` | string | yes | UUID. |
| `data[].event_id` | string \| null | yes |  |
| `data[].event_type` | string | yes |  |
| `data[].subject_id` | string | yes | UUID. |
| `data[].status` | "pending" \| "delivered" \| "failed" | yes |  |
| `data[].attempts` | integer | yes |  |
| `data[].max_attempts` | integer | yes |  |
| `data[].next_attempt_at` | string \| null | yes |  |
| `data[].last_attempt_at` | string \| null | yes |  |
| `data[].last_response_status` | integer \| null | yes |  |
| `data[].last_error` | string \| null | yes |  |
| `data[].delivered_at` | string \| null | yes |  |
| `data[].created_at` | string | yes | ISO 8601 timestamp (UTC). |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X GET 'https://startup-seeker.com/api/v4/webhooks/<id>/deliveries' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY"

```

### POST /api/v4/webhooks/{id}/deliveries/{delivery_id}/redeliver

**Redeliver** (`redeliver`). Send a delivery again now (one more attempt).

Free. API key required. Success: `202`. Accepts `Idempotency-Key`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Webhook UUID. |
| `delivery_id` | string | yes | Delivery UUID. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The result. |
| `data.id` | string | yes | UUID. |
| `data.status` | "pending" | yes |  |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/webhooks/<id>/deliveries/<delivery_id>/redeliver' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

```

## Error catalog

Every error has this shape: `{"error": {"code", "message", "param"?, "hint"?, "retryable", "doc_url", "details"?}}`. One HTTP status per code.

| Status | Code | Meaning | What to do | Retry |
| --- | --- | --- | --- | --- |
| 400 | `COLUMN_NAME_CONFLICT` | Two aggregate columns would have the same name. | Give one of the metrics an explicit `as` name. | no |
| 400 | `CURSOR_INVALID` | The cursor is malformed, belongs to another query or another account. | Send the cursor exactly as returned, with the same API key, or start again without a cursor. | no |
| 400 | `OPERATOR_NOT_SUPPORTED` | The operator is not available for this field. | Use one of the operators listed for the field in /schema. | no |
| 400 | `QUERY_TOO_COMPLEX` | The filter exceeds the complexity limits. | Stay within 3 nesting levels, 30 predicates and 100 values per array. | no |
| 400 | `SEMANTIC_NOT_SUPPORTED` | Semantic ranking (query / similar_to) is only available for startups. | Use a `text` match filter on other collections. | no |
| 400 | `TAG_ARRAY_NEEDS_OPERATOR` | A bare array was given for a tag field. | Say whether any or all values must match: {"any": [...]} or {"all": [...]}. | no |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. | Use a name from GET /schema/{collection}; `details.did_you_mean` lists close matches. | no |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. | Correct the field named in `param` using `hint`. | no |
| 400 | `VALUE_AMBIGUOUS` | A friendly filter value matches several canonical values. | Pick one of `details.candidates`. | no |
| 400 | `VALUE_UNKNOWN` | A filter value does not match any known value. | Use a canonical value; `details.did_you_mean` lists close matches. | no |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. | Send `Authorization: Bearer ssk_live_…` with an active key from /account/api-keys. | no |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. | Top up the balance, then retry. | no |
| 403 | `FORBIDDEN` | This key or application may not perform the operation. | For OAuth apps, grant the permission on the StartupSeeker consent screen. | no |
| 403 | `SPEND_LIMIT_EXCEEDED` | A per-job or daily enrichment spend limit would be exceeded. | Reduce the job or wait until `details.resets_at`. | no |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. | Check the id or ref; resources are account-scoped. | no |
| 404 | `RECORD_REMOVED` | The record was suppressed or deleted. | Remove the ref from your system. | no |
| 405 | `METHOD_NOT_ALLOWED` | The endpoint exists but not with this HTTP method. | Use a method listed in the Allow header. | no |
| 409 | `CHECK_ONLY_JOB` | A check-only enrichment has nothing to approve or configure. | Read its results, or create a job without check_only. | no |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. | Read the resource and retry the change. | no |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. | Retry the identical request with the same key after `Retry-After`. | yes |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. | Use a new key for a different request. | no |
| 409 | `JOB_NOT_CONFIGURABLE` | The job can no longer be reconfigured. | Only jobs awaiting approval can change; create a new job instead. | no |
| 409 | `PRICE_CHANGED` | The price rose since the quote was issued. | Review `details.quote` and approve its quote_id. | no |
| 409 | `QUOTE_EXPIRED` | The quote is older than 30 minutes or was replaced. | Approve the new quote in `details.quote` (or read the job for it). | no |
| 409 | `QUOTE_NOT_READY` | The job is still quoting. | Wait for status awaiting_approval (GET with ?wait=10). | yes |
| 409 | `REF_AMBIGUOUS` | The ref matches several records. | Use one of the UUIDs in `details.candidates`. | no |
| 410 | `CURSOR_EXPIRED` | The cursor expired (24 h, or 30 min for semantic rankings). | Run the query again without a cursor. | no |
| 410 | `SEARCH_EXPIRED` | The ranked search (search_id) expired after 30 minutes. | Run the semantic search again and use its new search_id. | no |
| 413 | `BODY_TOO_LARGE` | The request body exceeds 16 KB. | Send fewer values; split large inputs across requests. | no |
| 413 | `RECORD_TOO_LARGE` | A single record exceeds the 1 MB response budget. | Request fewer fields or expands. | no |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. | Wait until `details.resets_at`; see GET /account. | yes |
| 429 | `RATE_LIMITED` | Too many requests in the current window. | Wait for `Retry-After` seconds. | yes |
| 500 | `INTERNAL_ERROR` | An unexpected server error. | Retry once; contact support with the request id if it persists. | yes |
| 500 | `MUTATION_OUTCOME_UNKNOWN` | The change may or may not have been applied. | Retry with the same Idempotency-Key; never with a new key. Read the resource to reconcile. | yes |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. | Retry after `Retry-After` seconds. | yes |
| 504 | `QUERY_TIMEOUT` | The query ran out of its time budget. | Retry once; if it repeats, narrow the filter. | yes |

## Fields: startups

| Field | Type | Filter | Sort | Group | Default | Meaning |
| --- | --- | --- | --- | --- | --- | --- |
| `id` | ref | in, nin | yes | yes | yes | Stable canonical entity UUID. |
| `slug` | text | eq, in, prefix, match | yes | yes | yes | Domain alias when available; UUID for domainless entities. |
| `name` | text | eq, in, prefix, match | yes | yes | yes | Public display name. |
| `domain` | text | eq, in, prefix, match | yes | yes | yes | Canonical domain, nullable for investors. |
| `linkedin_url` | text | eq, in, prefix, match | yes | yes |  | Public LinkedIn company URL. |
| `hq_country` | enum | eq, ne, in, nin, exists | yes | yes | yes | Headquarters country ISO 3166-1 alpha-2. |
| `hq_admin1` | text | eq, in, prefix, match | yes | yes |  | Headquarters country-qualified administrative area code. |
| `hq_city` | text | eq, in, prefix, match | yes | yes |  | Headquarters GeoNames city identifier. |
| `hq_region` | tags | any, all, none, empty |  | yes |  | Country-level geographic region slugs of the headquarters; overlapping groups such as Europe and EMEA are returned together. Values: north_america, south_america, central_america, caribbean, latam, europe, european_union, asia, middle_east, mena, africa, oceania, south_asia, se_asia, greater_china, uk_ireland, dach, nordics, benelux, baltics, americas, apac, emea. |
| `founded_year` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Year founded. |
| `employees` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Latest evidenced employee count. |
| `linkedin_followers` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Latest LinkedIn follower count. |
| `refreshed_at` | datetime | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Time the serving projection was refreshed; does not imply returned data changed. |
| `description` | text | eq, in, prefix, match | yes | yes | yes | Short startup description. |
| `status` | enum | eq, ne, in, nin, exists | yes | yes | yes | Current lifecycle status. Values: active, inactive, acquired, shut_down, unknown. |
| `industries` | tags | any, all, none, empty |  | yes | yes | Canonical industry taxonomy slugs. |
| `locations` | relation | in, nin |  |  |  | Any evidenced office location; ISO2 country, admin1 code, region slug or GeoNames city ID. |
| `score` | number | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes | yes | Startup traction score. |
| `total_funding_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes | yes | Effective lifetime funding total using human-lock and lifetime-total precedence. |
| `last_round_type` | enum | eq, ne, in, nin, exists | yes | yes | yes | Public normalized funding round type. Values: pre_seed, seed, pre_series_a, series_a, series_b, series_c, series_d, series_e, series_f, series_g_plus, growth, bridge, angel, convertible_note, equity_crowdfunding, debt, grant, accelerator, strategic, private_equity, token_sale, post_ipo, undisclosed. |
| `last_round_at` | date | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Latest effective accepted round date. |
| `last_round_amount_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Amount of the latest effective accepted round. |
| `funding_rounds_count` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Number of effective accepted funding rounds. |
| `investor_count` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Distinct linked investor entities. |
| `investors` | relation | in, nin, role |  |  |  | Linked investor at startup level or in any accepted round. |
| `funding_rounds` | relation | some |  |  |  | Any effective accepted funding round. |
| `lists` | relation | in, nin |  |  |  | Owned saved list membership. |
| `added_at` | datetime | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Canonical entity creation time. |

**Expand:** `funding_rounds` (up to 20 per record), `investors` (up to 25 per record), `founders` (up to 10 per record), `locations` (up to 25 per record), `sources` (up to 5 per record).

## Fields: investors

| Field | Type | Filter | Sort | Group | Default | Meaning |
| --- | --- | --- | --- | --- | --- | --- |
| `id` | ref | in, nin | yes | yes | yes | Stable canonical entity UUID. |
| `slug` | text | eq, in, prefix, match | yes | yes | yes | Domain alias when available; UUID for domainless entities. |
| `name` | text | eq, in, prefix, match | yes | yes | yes | Public display name. |
| `domain` | text | eq, in, prefix, match | yes | yes | yes | Canonical domain, nullable for investors. |
| `linkedin_url` | text | eq, in, prefix, match | yes | yes |  | Public LinkedIn company URL. |
| `hq_country` | enum | eq, ne, in, nin, exists | yes | yes | yes | Headquarters country ISO 3166-1 alpha-2. |
| `hq_admin1` | text | eq, in, prefix, match | yes | yes |  | Headquarters country-qualified administrative area code. |
| `hq_city` | text | eq, in, prefix, match | yes | yes |  | Headquarters GeoNames city identifier. |
| `hq_region` | tags | any, all, none, empty |  | yes |  | Country-level geographic region slugs of the headquarters; overlapping groups such as Europe and EMEA are returned together. Values: north_america, south_america, central_america, caribbean, latam, europe, european_union, asia, middle_east, mena, africa, oceania, south_asia, se_asia, greater_china, uk_ireland, dach, nordics, benelux, baltics, americas, apac, emea. |
| `founded_year` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Year founded. |
| `employees` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Latest evidenced employee count. |
| `linkedin_followers` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Latest LinkedIn follower count. |
| `refreshed_at` | datetime | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Time the serving projection was refreshed; does not imply returned data changed. |
| `organization_types` | tags | any, all, none, empty |  | yes |  | Canonical investor organization types. |
| `aum_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Estimated assets under management. |
| `check_size_min_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | min recorded firm-level investment check size in USD. Legacy zero/nonpositive values are unknown (null), never a confirmed bound. Positive recorded bounds are not independent source verification and do not prove a specific strategy accepts the amount. |
| `check_size_typ_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | typ recorded firm-level investment check size in USD. Legacy zero/nonpositive values are unknown (null), never a confirmed bound. Positive recorded bounds are not independent source verification and do not prove a specific strategy accepts the amount. |
| `check_size_max_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | max recorded firm-level investment check size in USD. Legacy zero/nonpositive values are unknown (null), never a confirmed bound. Positive recorded bounds are not independent source verification and do not prove a specific strategy accepts the amount. |
| `stages` | tags | any, all, none, empty |  | yes |  | Firm-wide investment stage keys, trimmed and case-insensitive; unfamiliar labels are preserved. A stage and industry may belong to different funds or strategies; inspect investment_thesis before asserting joint fit. |
| `geo_scope` | tags | any, all, none, empty |  | yes |  | Geographic investment scope. |
| `target_industries` | tags | any, all, none, empty |  | yes |  | Firm-wide target industry taxonomy slugs; independent of stage tags, not proof that one strategy targets both. |
| `investment_thesis` | text | eq, in, prefix, match | yes | yes |  | Public investment thesis. Use explicit stage/sector/strategy linkage; split strategies and omissions cannot establish a joint fit from firm tags alone. |
| `portfolio_claimed_count` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes | yes | Distinct companies claimed in portfolio sources, including unresolved companies. |
| `portfolio_linked_count` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes | yes | Distinct linked startup entities in portfolio. |
| `average_portfolio_score` | number | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Average score of linked portfolio companies. |
| `portfolio_quality_score` | number | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes | yes | UI portfolio quality score. |
| `top_industries` | text | eq, in, prefix, match | yes | yes | yes | Most common industries among linked portfolio companies with their share of companies whose industry is known, e.g. "cleantech 62%\|energy 31%". Observed portfolio mix, not a stated mandate. For sector specialists rank with search focus. |
| `lead_preference` | enum | eq, ne, in, nin, exists | yes | yes |  | Preference for leading investments. |
| `last_deal_at` | date | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Latest accepted funding round participation. |
| `deals_last_12m` | integer | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Distinct accepted rounds participated in during the trailing 12 months. |
| `portfolio` | relation | count, some |  |  |  | Distinct linked portfolio startups matching where. |
| `deals` | relation | count, some, role |  |  |  | Distinct accepted rounds matching where and optional lead/participant role. |

**Expand:** `partners` (up to 10 per record), `portfolio` (up to 25 per record), `funds` (up to 20 per record), `co_investors` (up to 25 per record), `deal_stats` (one record), `sources` (up to 5 per record).

## Fields: funding_rounds

| Field | Type | Filter | Sort | Group | Default | Meaning |
| --- | --- | --- | --- | --- | --- | --- |
| `id` | ref | in, nin | yes | yes | yes | Stable accepted funding round UUID. |
| `startup_id` | ref | in, nin | yes | yes | yes | Canonical startup entity UUID. |
| `round_type` | enum | eq, ne, in, nin, exists | yes | yes | yes | Public normalized funding round type. Values: pre_seed, seed, pre_series_a, series_a, series_b, series_c, series_d, series_e, series_f, series_g_plus, growth, bridge, angel, convertible_note, equity_crowdfunding, debt, grant, accelerator, strategic, private_equity, token_sale, post_ipo, undisclosed. |
| `round_variant` | enum | eq, ne, in, nin, exists | yes | yes |  | Extension, tranche or follow-on. Values: extension, tranche, follow_on. |
| `announced_at` | date | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes | yes | Announced date of effective round. |
| `amount_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes | yes | Disclosed funding amount in USD. |
| `valuation_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Disclosed valuation; interpret with valuation_basis. |
| `valuation_basis` | enum | eq, ne, in, nin, exists | yes | yes |  | Valuation basis. Values: pre_money, post_money, unspecified. |
| `currency_original` | enum | eq, ne, in, nin, exists | yes | yes |  | Original disclosed ISO currency. |
| `is_partial` | boolean | eq, exists | yes | yes |  | Whether accepted round data is partial. |
| `hq_country` | enum | eq, ne, in, nin, exists | yes | yes | yes | Headquarters country ISO 3166-1 alpha-2. |
| `hq_admin1` | text | eq, in, prefix, match | yes | yes |  | Headquarters country-qualified administrative area code. |
| `hq_city` | text | eq, in, prefix, match | yes | yes |  | Headquarters GeoNames city identifier. |
| `hq_region` | tags | any, all, none, empty |  | yes |  | Country-level geographic region slugs of the headquarters; overlapping groups such as Europe and EMEA are returned together. Values: north_america, south_america, central_america, caribbean, latam, europe, european_union, asia, middle_east, mena, africa, oceania, south_asia, se_asia, greater_china, uk_ireland, dach, nordics, benelux, baltics, americas, apac, emea. |
| `industries` | tags | any, all, none, empty |  | yes |  | Startup industry taxonomy slugs. |
| `investors` | relation | in, nin, role |  |  |  | Linked accepted round investor role edges. |
| `startup` | relation | some |  |  |  | Filter the linked startup. |

**Expand:** `investors` (up to 25 per record), `startup` (one record), `sources` (up to 5 per record).

## Fields: exits

| Field | Type | Filter | Sort | Group | Default | Meaning |
| --- | --- | --- | --- | --- | --- | --- |
| `id` | ref | in, nin | yes | yes | yes | Stable accepted exit event UUID. |
| `startup_id` | ref | in, nin | yes | yes | yes | Canonical startup entity UUID. |
| `exit_type` | enum | eq, ne, in, nin, exists | yes | yes | yes | Acquisition or IPO. Values: acquisition, ipo. |
| `event_date` | date | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes | yes | Accepted exit event date. |
| `price_usd` | money (USD) | eq, in, ne, gt, gte, lt, lte, between, exists | yes | yes |  | Disclosed acquisition or IPO price in USD. |
| `acquirer_id` | ref | in, nin | yes | yes |  | Resolved acquirer canonical entity UUID. |
| `acquirer_name` | text | eq, in, prefix, match | yes | yes |  | Acquirer display name. |
| `acquirer_domain` | text | eq, in, prefix, match | yes | yes |  | Acquirer domain. |
| `hq_country` | enum | eq, ne, in, nin, exists | yes | yes | yes | Headquarters country ISO 3166-1 alpha-2. |
| `hq_admin1` | text | eq, in, prefix, match | yes | yes |  | Headquarters country-qualified administrative area code. |
| `hq_city` | text | eq, in, prefix, match | yes | yes |  | Headquarters GeoNames city identifier. |
| `hq_region` | tags | any, all, none, empty |  | yes |  | Country-level geographic region slugs of the headquarters; overlapping groups such as Europe and EMEA are returned together. Values: north_america, south_america, central_america, caribbean, latam, europe, european_union, asia, middle_east, mena, africa, oceania, south_asia, se_asia, greater_china, uk_ireland, dach, nordics, benelux, baltics, americas, apac, emea. |
| `industries` | tags | any, all, none, empty |  | yes |  | Startup industry taxonomy slugs. |
| `startup` | relation | some |  |  |  | Filter the linked startup. |
| `acquirer` | relation | in, nin |  |  |  | Acquirer UUID, domain or exact name. |

**Expand:** `startup` (one record), `acquirer` (one record), `sources` (up to 5 per record).