StartupSeeker Public API v1

This reference documents the legacy v1 compatibility API. The page and Markdown export are generated from the same v1 endpoint catalog so migrations stay explicit.

Official Surface

The reference covers the legacy compatibility surface: `/api/v1/*` endpoints plus the deprecated `/api/deep-research` route.

Current Behavior

The docs intentionally preserve the current v1 compatibility shapes, including the remaining envelope and access differences between routes.

Generated Markdown

Use the export below when you need to feed the selected API version to an LLM, internal tool, or external consumer.

Copy Docs for LLMs

Copy the same V1 public API reference that powers this page, formatted as Markdown.

Authentication and Access Modes

The legacy v1 surface is still mixed: most routes require API keys, while the two classifier endpoints remain anonymous and IP-limited.

API-key routes

`/api/v1/search`, `/api/v1/enrich`, `/api/v1/competitors`, `/api/v1/parse-deck`, and `/api/deep-research` require a StartupSeeker API key.

Authorization: Bearer ssk_live_your_api_key

Anonymous IP-limited routes

`/api/v1/vc-backable-classifier` and `/api/v1/vc-backable-minimum` do not currently require API keys and are enforced by IP-based quotas.

v1 compatibility notice

`/api/deep-research` remains documented as a legacy route, but public access is now API-key-only and new integrations should move to `/api/v2/deep-research-jobs`.

POST/api/v1/enrich
Free

Enrich API

Look up a company by website and return the matching StartupSeeker company record, if one exists.

This route currently costs 0 credits per request.

Method
POST
Path
/api/v1/enrich
Content-Type
application/json
Credits
0 per request

Request Shape

{
  "request_id": "enrich-demo-1",
  "website": "stripe.com"
}

Request Fields

NameTypeRequiredDescription
request_idstring | nullNoOptional client correlation ID. Maximum 128 characters.
websitestringYesCompany website or domain to normalize and look up.

Response Fields

NameTypeRequiredDescription
request_idstring | nullNoEchoes the provided request ID.
websiteobjectNoContains both `submitted` and normalized website values.
companyobject | nullNoMatching company record, or `null` when no record exists.
missingbooleanNoConvenience flag; `true` when `company` is `null`.
rate_limitobjectNoMinute/day quota snapshot mirrored from the response headers.

Sample Request

curl -X POST https://startup-seeker.com/api/v1/enrich \
  -H "Authorization: Bearer ssk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "enrich-demo-1",
    "website": "stripe.com"
  }'

Sample Response

{
  "request_id": "enrich-demo-1",
  "website": {
    "submitted": "stripe.com",
    "normalized": "stripe.com"
  },
  "company": {
    "id": "458861125612149361",
    "name": "Stripe",
    "website": "stripe.com",
    "description": "Payments infrastructure for internet businesses."
  },
  "missing": false,
  "rate_limit": {
    "minute": {
      "limit": 30,
      "remaining": 29,
      "reset_at": 1712083200000
    },
    "day": {
      "limit": 100,
      "remaining": 99,
      "reset_at": 1712126400000
    }
  }
}

Important Headers

HeaderDescription
AuthorizationRequired. `Bearer ssk_live_...` or `ssk_test_...` API key.
X-RateLimit-Limit-MinuteEffective per-minute limit for the key/account.
X-RateLimit-Limit-DayEffective per-day limit for the key/account.
X-Credits-RemainingRemaining API credits after the request finalizes.

Common Errors

StatusCodeDescription
400BAD_REQUESTInvalid JSON or invalid website input.
401UNAUTHORIZEDMissing or invalid API key.
429RATE_LIMITEDPer-key or per-account quota exceeded.
500INTERNAL_ERRORWebsite lookup service is not configured or failed.

Implementation Notes

  • The endpoint normalizes the submitted website before lookup.
  • A 200 response with `"missing": true` is the expected result when StartupSeeker has no matching company.
POST/api/v1/competitors
1 credit / request

Competitors API

Run AI-powered competitor analysis from a company website or a sufficiently detailed company description.

This route currently costs 1 credit per request.

Method
POST
Path
/api/v1/competitors
Content-Type
application/json
Credits
1 per request

Request Shape

{
  "company": {
    "name": "Acme Analytics",
    "website": "acmeanalytics.com"
  }
}

Request Fields

NameTypeRequiredDescription
company.namestring | nullNoOptional company name used to improve the resolved context.
company.websitestring | nullNoOptional website. Provide this whenever possible for better resolution.
company.descriptionstring | nullNoOptional company description. Required when no website is provided and must then be at least 20 characters.

Response Fields

NameTypeRequiredDescription
dataarray<object>NoCompetitor matches and AI-generated summaries.
companyobjectNoContains the input payload and the resolved company context used by the analysis.
rate_limitobjectNoMinute/day quota snapshot mirrored from the response headers.

Sample Request

curl -X POST https://startup-seeker.com/api/v1/competitors \
  -H "Authorization: Bearer ssk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "company": {
      "name": "Acme Analytics",
      "website": "acmeanalytics.com"
    }
  }'

Sample Response

{
  "company": {
    "input": {
      "name": "Acme Analytics",
      "website": "acmeanalytics.com",
      "description": null
    },
    "resolved": {
      "name": "Acme Analytics",
      "normalized_website": "acmeanalytics.com",
      "description": "SaaS analytics platform for B2B companies"
    }
  },
  "data": [
    {
      "company": {
        "name": "DataViz Pro",
        "website": "datavizpro.io",
        "description": "Business intelligence platform"
      },
      "similarity_level": "HIGH",
      "summary": "DataViz Pro overlaps with Acme Analytics in analytics workflows and target buyers."
    }
  ],
  "rate_limit": {
    "minute": {
      "limit": 30,
      "remaining": 29,
      "reset_at": 1712083200000
    },
    "day": {
      "limit": 100,
      "remaining": 99,
      "reset_at": 1712126400000
    }
  }
}

Important Headers

HeaderDescription
AuthorizationRequired. `Bearer ssk_live_...` or `ssk_test_...` API key.
X-RateLimit-Limit-MinuteEffective per-minute limit for the key/account.
X-RateLimit-Limit-DayEffective per-day limit for the key/account.
X-Credits-RemainingRemaining API credits after the request finalizes.

Common Errors

StatusCodeDescription
400BAD_REQUESTInvalid JSON, missing both website and description, or description too short.
401UNAUTHORIZEDMissing or invalid API key.
402INSUFFICIENT_CREDITSAccount has no remaining API credits.
429RATE_LIMITEDPer-key or per-account quota exceeded.
500INTERNAL_ERRORCompetitor analysis failed.

Implementation Notes

  • Either `company.website` or `company.description` must be present.
  • When only a description is provided, make it specific; short descriptions are rejected.
POST/api/v1/vc-backable-classifier
Not metered today

VC Backable Classifier

Batch-classify domains as VC-backable, with full descriptions and raw homepage scrape content.

Anonymous access is allowed and IP-rate-limited.

This route is not credit-metered today.

Method
POST
Path
/api/v1/vc-backable-classifier
Auth
anonymous_ip_limited
Content-Type
application/json
Credits
Not metered

Request Shape

{
  "websites": ["runwayml.com", "genei.io"],
  "include_description": true
}

Request Fields

NameTypeRequiredDescription
websitesarray<string>NoPreferred batch input. Supply one or more websites/domains.
websitestringNoSingle-site shortcut when not using `websites`.
include_descriptionbooleanNoOptional. Defaults to `true` on this full endpoint.

Response Fields

NameTypeRequiredDescription
countnumberNoNumber of entries returned in `data`.
dataarray<object>NoClassification results with `website`, `name`, `description`, `vc_investable`, and `homepage_scrape`.
rate_limitobjectNoBody copy of the second/minute/day rate-limit state.

Sample Request

curl -X POST https://startup-seeker.com/api/v1/vc-backable-classifier \
  -H "Content-Type: application/json" \
  -d '{
    "websites": ["runwayml.com", "genei.io"],
    "include_description": true
  }'

Sample Response

{
  "count": 2,
  "data": [
    {
      "website": "runwayml.com",
      "name": "Runway",
      "description": "Runway delivers AI-powered creative tools for video and image generation.",
      "vc_investable": "Yes",
      "homepage_scrape": "<html>...</html>"
    },
    {
      "website": "genei.io",
      "name": "Genei",
      "description": "Genei helps knowledge workers summarize research content.",
      "vc_investable": "Likely Not",
      "homepage_scrape": ""
    }
  ],
  "rate_limit": {
    "second": {
      "limit": 500,
      "remaining": 498,
      "reset_at": 1736831400000
    },
    "minute": {
      "limit": 10000,
      "remaining": 9998,
      "reset_at": 1736831460000
    },
    "day": {
      "limit": 50000,
      "remaining": 49998,
      "reset_at": 1736914200000
    }
  }
}

Important Headers

HeaderDescription
X-RateLimit-Limit-SecondPer-IP second limit.
X-RateLimit-Limit-MinutePer-IP minute limit.
X-RateLimit-Limit-DayPer-IP day limit.

Common Errors

StatusCodeDescription
400BAD_REQUESTRequest omitted both `website` and `websites`, or a website is invalid.
429RATE_LIMITEDPer-IP quota exceeded.
500INTERNAL_ERRORRequired scraping configuration is missing or classification failed.

Implementation Notes

  • This endpoint is not credit-metered today.
  • Domains are normalized and deduplicated before processing.
POST/api/v1/vc-backable-minimum
Not metered today

VC Backable Minimum

Low-payload VC-backability classifier that returns only the verdict map, with optional descriptions.

Anonymous access is allowed and IP-rate-limited.

This route is not credit-metered today.

Method
POST
Path
/api/v1/vc-backable-minimum
Auth
anonymous_ip_limited
Content-Type
application/json
Credits
Not metered

Request Shape

{
  "websites": ["runwayml.com", "genei.io"],
  "include_description": false
}

Request Fields

NameTypeRequiredDescription
websitesarray<string>NoPreferred batch input. Supply one or more websites/domains.
websitestringNoSingle-site shortcut when not using `websites`.
include_descriptionbooleanNoOptional. Defaults to `false` on this minimal endpoint.

Response Fields

NameTypeRequiredDescription
dataobjectNoMap keyed by normalized website. Each value contains `classification` and optional `description`.

Sample Request

curl -X POST https://startup-seeker.com/api/v1/vc-backable-minimum \
  -H "Content-Type: application/json" \
  -d '{
    "websites": ["runwayml.com", "genei.io"]
  }'

Sample Response

{
  "data": {
    "runwayml.com": {
      "classification": "Yes"
    },
    "genei.io": {
      "classification": "Likely Not"
    }
  }
}

Important Headers

HeaderDescription
X-RateLimit-Limit-SecondPer-IP second limit.
X-RateLimit-Limit-MinutePer-IP minute limit.
X-RateLimit-Limit-DayPer-IP day limit.

Common Errors

StatusCodeDescription
400BAD_REQUESTRequest omitted both `website` and `websites`, or a website is invalid.
429RATE_LIMITEDPer-IP quota exceeded.
500INTERNAL_ERRORRequired scraping configuration is missing or classification failed.

Implementation Notes

  • This endpoint is not credit-metered today.
  • Use `include_description: true` if you want a short description alongside the verdicts.
POST/api/v1/parse-deck
5 credits / request

Pitch Deck Parser

Upload a PDF pitch deck and get per-slide summaries plus a combined markdown representation.

This route currently costs 5 credits per request.

Method
POST
Path
/api/v1/parse-deck
Content-Type
multipart/form-data
Credits
5 per request

Request Shape

multipart/form-data
- file: <PDF, required>
- request_id: <string, optional>

Request Fields

NameTypeRequiredDescription
fileFile (PDF)YesPitch deck PDF. Maximum size is 30 MB.
request_idstring | nullNoOptional client correlation ID.

Response Fields

NameTypeRequiredDescription
request_idstring | nullNoEchoes the provided request ID.
filenamestringNoOriginal uploaded filename.
total_pagesnumberNoTotal number of PDF pages in the uploaded file.
processed_slidesnumberNoNumber of slides actually processed. Maximum 30.
slidesarray<object>NoPer-slide summaries with `page_number` and `summary`.
markdownstringNoCombined markdown output generated from the processed slides.
rate_limitobjectNoMinute/day quota snapshot mirrored from the response headers.

Sample Request

curl -X POST https://startup-seeker.com/api/v1/parse-deck \
  -H "Authorization: Bearer ssk_live_your_api_key" \
  -F "file=@pitch-deck.pdf" \
  -F "request_id=deck-demo-1"

Sample Response

{
  "request_id": "deck-demo-1",
  "filename": "pitch-deck.pdf",
  "total_pages": 12,
  "processed_slides": 12,
  "slides": [
    {
      "page_number": 1,
      "summary": "Title slide introducing the company and market."
    }
  ],
  "markdown": "## Slide 1\n\nTitle slide introducing the company and market.",
  "rate_limit": {
    "minute": {
      "limit": 30,
      "remaining": 29,
      "reset_at": 1712083200000
    },
    "day": {
      "limit": 100,
      "remaining": 99,
      "reset_at": 1712126400000
    }
  }
}

Important Headers

HeaderDescription
AuthorizationRequired. `Bearer ssk_live_...` or `ssk_test_...` API key.
X-RateLimit-Limit-MinuteEffective per-minute limit for the key/account.
X-RateLimit-Limit-DayEffective per-day limit for the key/account.
X-Credits-RemainingRemaining API credits after the request finalizes.
X-Credits-ChargedCredits charged for this request. Always `5` on successful or partial-successful processing.

Common Errors

StatusCodeDescription
400INVALID_REQUESTBody was not multipart/form-data, the file is missing, or the file is not a valid PDF.
400INVALID_FILE_TYPEUploaded file is not a PDF.
413FILE_TOO_LARGEUploaded PDF exceeds the 30 MB limit.
207MULTI_STATUSPartial success: one or more slides failed to process, but the request still returned usable output.
401UNAUTHORIZEDMissing or invalid API key.
402INSUFFICIENT_CREDITSAccount has no remaining API credits.

Implementation Notes

  • Only the first 30 slides are processed; extra pages are ignored but still counted in `total_pages`.
  • This endpoint can return HTTP 207 when some slides fail and others succeed.
POST/api/deep-research
10 credits / request

Deep Research API

Run a multi-step research workflow that combines deep scrape, founders, funding, LinkedIn, scoring, and optional competitors.

This route currently costs 10 credits per request.

Method
POST
Path
/api/deep-research
Content-Type
application/json
Credits
10 per request

Request Shape

{
  "website": "exa.ai",
  "include_competitors": true,
  "context": "Optional analyst notes",
  "company_name": "Exa"
}

Request Fields

NameTypeRequiredDescription
websitestringYesWebsite/domain to research.
zilliz_idstringNoOptional existing StartupSeeker record ID.
include_competitorsbooleanNoOptional. Defaults to `true`. Set to `false` to skip competitor analysis.
city / country / country_isostringNoOptional location overrides used during the workflow.
contextstringNoOptional extra context. Public API requests are API-key-owned; signed-in app flows use internal job routes.
company_namestringNoOptional company name override.

Response Fields

NameTypeRequiredDescription
successbooleanNoTrue when at least some of the research workflow succeeded.
zilliz_idstring | nullNoResolved or newly-linked company record ID.
timestampstringNoISO timestamp for completion time.
used_custom_context / context_truncated / warningmixedNoContext-related flags when custom context was provided.
dataobjectNoResearch subsystem results including `deepScrape`, `founders`, `funding`, `linkedin`, `scoring`, `zillizUpdate`, and optional `competitors`.
errorsobjectNoPer-subsystem error messages for partial failures.
summaryobjectNoExecution counts and total duration.
rate_limitobjectNoReturned for API-key requests.

Sample Request

curl -X POST https://startup-seeker.com/api/deep-research \
  -H "Authorization: Bearer ssk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "website": "exa.ai",
    "include_competitors": false,
    "company_name": "Exa"
  }'

Sample Response

{
  "success": true,
  "zilliz_id": "458861125612149361",
  "timestamp": "2026-03-14T11:04:32.102Z",
  "data": {
    "deepScrape": {
      "status": "fulfilled",
      "website": "exa.ai",
      "concise_description": "AI-native search engine for the web."
    },
    "founders": {
      "status": "fulfilled",
      "data": {
        "founders": []
      }
    },
    "funding": {
      "status": "fulfilled",
      "data": {
        "total_funding": 107000000
      }
    },
    "linkedin": {
      "status": "fulfilled",
      "data": {
        "followers": 22841,
        "employees": 92
      }
    },
    "scoring": {
      "status": "fulfilled",
      "score": 0.82
    },
    "zillizUpdate": {
      "status": "fulfilled"
    }
  },
  "errors": {},
  "summary": {
    "total_requests": 5,
    "successful": 5,
    "failed": 0,
    "execution_time_ms": 32450,
    "competitors_skipped": true
  },
  "rate_limit": {
    "minute": {
      "limit": 30,
      "remaining": 29,
      "reset_at": 1712083200000
    },
    "day": {
      "limit": 100,
      "remaining": 99,
      "reset_at": 1712126400000
    }
  }
}

Important Headers

HeaderDescription
AuthorizationRequired. `Bearer ssk_live_...` or `ssk_test_...` API key.
Retry-AfterReturned for API-key rate-limit responses.
X-Credits-RemainingReturned for API-key requests.

Common Errors

StatusCodeDescription
400BAD_REQUESTMissing or invalid `website`, or invalid JSON body.
401UNAUTHORIZEDMissing or invalid API key.
402INSUFFICIENT_CREDITSAPI-key request is valid but the account has no remaining credits.
429RATE_LIMITEDAPI-key quota exceeded.
500INTERNAL_ERRORWorkflow failed before producing a usable partial response.

Implementation Notes

  • Public access to `/api/deep-research` is API-key-only.
  • Signed-in browser/app flows should use internal deep-research job routes instead of the public API path.
  • Typical runtime is much longer than the other public endpoints, especially when `include_competitors` is `true`.
  • Response and error envelopes are intentionally documented as-is; they are not fully aligned with the `/api/v1/*` routes.

Rate Limits

v1 still spans two rate-limit families: metered API-key routes and anonymous IP-limited classifier routes.

Default API key quota
5/sec
30/min
100/day
Classifier IP limits
500/sec
10000/min
50000/day

Header Behavior

  • Metered API-key routes return `X-RateLimit-*` headers and `X-Credits-Remaining`.
  • `/api/v1/parse-deck` also returns `X-Credits-Charged`.
  • IP-limited classifier routes return `X-RateLimit-*` headers but no credit headers.

Errors

Error envelopes are not fully standardized across the v1 compatibility surface. The endpoint sections above show the route-specific status codes and error codes you should expect.

Flat error envelope

Most metered v1 routes use a flat JSON object with `error`, `code`, and optional `meta`.

{
  "error": "Invalid request body: Query must be at least 3 characters long.",
  "code": "BAD_REQUEST"
}

Nested error envelope

The classifier routes and parse-deck route currently return nested error objects.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "A PDF file is required. Use the \"file\" field."
  }
}

Important caveat

Treat each route as its own contract. If you are building an SDK or proxy, branch on the endpoint instead of assuming a single shared error schema across the entire public API.

StartupSeeker - Startup Search Engine