{ "openapi": "3.0.3", "info": { "title": "Parsers VC API", "version": "2.1.0", "description": "Venture capital data: funds, startups, funding rounds, valuations, people and news.\n\nTwo hosts are described here. Data lives on `https://vcapi.parsers.vc/v2`; the endpoints that hand out an API key live on `https://parsers.vc/api/v1` and each of those declares its own `servers` entry.\n\nTwo entry points are worth knowing before the collections. `GET /categories` answers \"what is in here and how is it divided up\", including a facet count across several axes in one request. `GET /signals` is the change feed - everything that moved, cursor paged, ordered by when this database recorded it rather than by the date the market puts on it.\n\nA credit buys a record rather than a call, so the page size is the bill; the rate card is under \"What a request costs\" below.\n\nIf you are an AI assistant with no key yet, you can obtain one yourself: `POST /auth/register` with the address of the person you are helping, then `POST /auth/verify` with the code they read out of the e-mail. Nobody has to open a browser or fill in a form. Instructions written for you: https://parsers.vc/api/v1/agents.md\n\n### What a request costs\n\nA credit buys one **record**, not one HTTP call: `credits = max(1, ceil(base + records * per_record * (1 + 0.25 * expands)))`. Startups, funds and people are 1 per record; funding rounds, valuations and portfolios 0.5; news, signals and mentions 0.25; the `/search` endpoints and `/categories` are a flat 1 whatever they return; `/find` is 25 and `/venturematching` 10. Errors cost nothing, and a query that matched nothing still costs the one-credit minimum.\n\n`$select` narrows the payload but not the price - to resolve names to ids cheaply, use `/startups/search` or `/funds/search`. Every metered response carries `X-Credits-Charged` alongside the `X-RateLimit-*` headers. `GET /pricing` returns the full rate card, free, and https://parsers.vc/api_page/pricing/ is the same thing for people.", "contact": { "name": "Parsers VC support", "email": "support@parsers.vc", "url": "https://parsers.vc/api_page/reference/" } }, "servers": [ { "url": "https://vcapi.parsers.vc/v2", "description": "Data API" } ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "tags": [ { "name": "Funds", "description": "Venture funds and what they invest in." }, { "name": "Startups", "description": "Companies, their funding and valuations." }, { "name": "People", "description": "Founders and investors." }, { "name": "News", "description": "Articles tied to a company." }, { "name": "Categories", "description": "Browsing the data by category: which axes exist, what values they take, how many entities carry each, and the entities themselves. Cheaper than guessing, and it is the only place that tells you what a valid value looks like." }, { "name": "Signals", "description": "The change feed. What was recorded, when it happened in the market, and when this database learned about it. Ordered and paged by the second of those - never the first." }, { "name": "Access", "description": "Getting and checking an API key. These live on parsers.vc, not on vcapi.parsers.vc." }, { "name": "Pricing", "description": "What a request costs, machine readable." } ], "paths": { "/funds": { "get": { "tags": [ "Funds" ], "operationId": "listFunds", "summary": "List venture funds", "description": "Free-tier callers get at most 100 rows per request; page with `$skip`.", "parameters": [ { "$ref": "#/components/parameters/Top" }, { "$ref": "#/components/parameters/Skip" }, { "$ref": "#/components/parameters/Filter" }, { "$ref": "#/components/parameters/Select" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/Count" } ], "responses": { "200": { "description": "Matching funds.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Fund" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/funds/{id}": { "get": { "tags": [ "Funds" ], "operationId": "getFund", "summary": "One fund by id", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Select" } ], "responses": { "200": { "description": "The fund.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fund" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/funds/search": { "get": { "tags": [ "Funds" ], "operationId": "searchFunds", "summary": "Find a fund by name or website", "description": "Use this to resolve a name a person typed into an id you can query with.", "parameters": [ { "name": "q", "in": "query", "description": "Free text, matched against the name.", "schema": { "type": "string" } }, { "name": "website", "in": "query", "description": "Exact website or domain.", "schema": { "type": "string" } }, { "name": "top", "in": "query", "description": "How many matches to return.", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Matches, best first.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyMatch" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/startups": { "get": { "tags": [ "Startups" ], "operationId": "listStartups", "summary": "List startups", "description": "Free-tier callers get at most 100 rows per request; page with `$skip`.", "parameters": [ { "$ref": "#/components/parameters/Top" }, { "$ref": "#/components/parameters/Skip" }, { "$ref": "#/components/parameters/Filter" }, { "$ref": "#/components/parameters/Select" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/Count" } ], "responses": { "200": { "description": "Matching startups.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Startup" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/startups/{id}": { "get": { "tags": [ "Startups" ], "operationId": "getStartup", "summary": "One startup by id", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Select" } ], "responses": { "200": { "description": "The startup.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Startup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/startups/search": { "get": { "tags": [ "Startups" ], "operationId": "searchStartups", "summary": "Find a startup by name or website", "parameters": [ { "name": "q", "in": "query", "description": "Free text, matched against the name.", "schema": { "type": "string" } }, { "name": "website", "in": "query", "description": "Exact website or domain.", "schema": { "type": "string" } }, { "name": "top", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Matches, best first.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyMatch" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/startups/fundingrounds": { "get": { "tags": [ "Startups" ], "operationId": "listFundingRounds", "summary": "Funding rounds across all startups", "description": "Filter by date to build a feed, e.g. `$filter=Date ge 2026-01-01`.", "parameters": [ { "$ref": "#/components/parameters/Top" }, { "$ref": "#/components/parameters/Skip" }, { "$ref": "#/components/parameters/Filter" }, { "$ref": "#/components/parameters/Select" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/Count" } ], "responses": { "200": { "description": "Funding rounds.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FundingRound" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/persons": { "get": { "tags": [ "People" ], "operationId": "listPersons", "summary": "List people", "parameters": [ { "$ref": "#/components/parameters/Top" }, { "$ref": "#/components/parameters/Skip" }, { "$ref": "#/components/parameters/Filter" }, { "$ref": "#/components/parameters/Select" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/Count" } ], "responses": { "200": { "description": "Matching people.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/persons/{id}": { "get": { "tags": [ "People" ], "operationId": "getPerson", "summary": "One person by id", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Select" } ], "responses": { "200": { "description": "The person.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/news": { "get": { "tags": [ "News" ], "operationId": "listNews", "summary": "List news items", "parameters": [ { "$ref": "#/components/parameters/Top" }, { "$ref": "#/components/parameters/Skip" }, { "$ref": "#/components/parameters/Filter" }, { "$ref": "#/components/parameters/Select" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/Count" } ], "responses": { "200": { "description": "News items.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NewsItem" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/companies/search": { "get": { "tags": [ "Startups" ], "operationId": "searchCompanies", "summary": "Find a company of either kind", "description": "Searches funds and startups together. Use it when you do not yet know which one a name refers to.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "website", "in": "query", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma separated list, e.g. `name,website`.", "schema": { "type": "string" } }, { "name": "top", "in": "query", "schema": { "type": "integer", "default": 5 } } ], "responses": { "200": { "description": "Matches.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyMatch" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/auth/register": { "post": { "tags": [ "Access" ], "operationId": "registerForKey", "summary": "Start registration and have a code e-mailed", "description": "Answers 202 whether or not the address was accepted, so this endpoint cannot be used to find out who is registered. Rate limited per address and per network.", "servers": [ { "url": "https://parsers.vc/api/v1", "description": "Access API" } ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "202": { "description": "Accepted. `request_id` is present only when a message was actually sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "sent" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "expires_in": { "type": "integer", "example": 600 }, "next": { "type": "string", "description": "What to do next, in plain words." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/auth/verify": { "post": { "tags": [ "Access" ], "operationId": "verifyCode", "summary": "Exchange the e-mailed code for an API key", "description": "The code is valid for ten minutes and five attempts. A key issued this way expires after 30 days.\n\nIdentify the registration with the `request_id` from `/auth/register`. If you no longer have it - typically because the person opened the register URL in their own browser, so the answer never reached you - send `email` instead: the code is then matched against the newest registration still open for that address. Send one or the other; `request_id` wins if both are present.", "servers": [ { "url": "https://parsers.vc/api/v1", "description": "Access API" } ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "anyOf": [ { "required": [ "request_id" ] }, { "required": [ "email" ] } ], "properties": { "request_id": { "type": "string", "description": "From /auth/register. Preferred." }, "email": { "type": "string", "format": "email", "description": "The address the code was sent to. Use only when request_id was lost; resolves to the newest open registration for it." }, "code": { "type": "string", "example": "123456" } } } } } }, "responses": { "200": { "description": "The key. Store it; it is not shown again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "example": "pk_live_7f3a..." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "email": { "type": "string" }, "credits": { "$ref": "#/components/schemas/Credits" }, "base_url": { "type": "string" }, "usage": { "type": "string" }, "docs_url": { "type": "string" }, "manage_url": { "type": "string" }, "notice": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Wrong code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The request expired or was already used. Register again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many attempts. Register again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/status": { "get": { "tags": [ "Access" ], "operationId": "registrationStatus", "summary": "Check whether the person finished in the browser", "description": "Poll this when they would rather not share the code and use the link in the e-mail instead.", "servers": [ { "url": "https://parsers.vc/api/v1", "description": "Access API" } ], "security": [], "parameters": [ { "name": "request_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Where the registration stands.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "link_used", "completed", "expired", "unknown" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/usage": { "get": { "tags": [ "Access" ], "operationId": "getUsage", "summary": "Credits left on a key", "description": "Every data response already carries `X-RateLimit-Remaining`; this is for checking without spending a request on the data API.", "servers": [ { "url": "https://parsers.vc/api/v1", "description": "Access API" } ], "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Current balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credits" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/categories": { "get": { "tags": [ "Categories" ], "operationId": "listCategoryDimensions", "summary": "Every way the data can be sliced", "description": "The catalogue of dimensions, with the complete value list for the closed ones. Read this before guessing at a dimension or a value name: it is one credit and it saves several.", "parameters": [ { "$ref": "#/components/parameters/CategoryEntity" } ], "responses": { "200": { "description": "The dimensions.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryDimension" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/categories/facets": { "get": { "tags": [ "Categories" ], "operationId": "getCategoryFacets", "summary": "Count several dimensions at once", "description": "One request, one credit, one count per dimension, all against the same narrowed set - the shape a filter sidebar needs, and the cheapest way to size a segment before querying it.\n\nA dimension is never constrained by its own selection: asking for `industry` while filtering on `industry=fintech` returns the alternatives, not an echo.\n\nAny dimension id may also be passed as a query parameter to narrow the set before counting - `?country=Germany&industry=fintech`. OpenAPI cannot express an open set of parameter names, so only the most used ones are declared below; the full list is at `GET /categories`. Values may be comma separated, and closed dimensions accept the label, the slug or the member name (\"Series A\" = \"series-a\" = \"SeriesA\").", "parameters": [ { "$ref": "#/components/parameters/CategoryEntity" }, { "name": "dimensions", "in": "query", "description": "Comma separated dimension ids, at most 10. Omit for every closed dimension of that entity.", "required": false, "schema": { "type": "string" } }, { "name": "top", "in": "query", "description": "Values per dimension. Default 25, max 500.", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 500 } }, { "$ref": "#/components/parameters/DimIndustry" }, { "$ref": "#/components/parameters/DimCountry" }, { "$ref": "#/components/parameters/DimRegion" }, { "$ref": "#/components/parameters/DimCity" }, { "$ref": "#/components/parameters/DimStage" }, { "$ref": "#/components/parameters/DimInvestorType" }, { "$ref": "#/components/parameters/DimInvestmentStage" } ], "responses": { "200": { "description": "Counts per dimension.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "narrowedBy": { "type": "object", "description": "The selections that were applied, echoed back with their resolved labels.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "facets": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryValue" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/categories/{dimension}": { "get": { "tags": [ "Categories" ], "operationId": "listCategoryValues", "summary": "The values on one axis, with counts", "description": "Most common first. Passing another dimension as a query parameter narrows the set first, which is what turns a list into a facet: `/categories/industry?country=Germany` is \"industries among German companies\".\n\nAny dimension id may also be passed as a query parameter to narrow the set before counting - `?country=Germany&industry=fintech`. OpenAPI cannot express an open set of parameter names, so only the most used ones are declared below; the full list is at `GET /categories`. Values may be comma separated, and closed dimensions accept the label, the slug or the member name (\"Series A\" = \"series-a\" = \"SeriesA\").", "parameters": [ { "name": "dimension", "in": "path", "required": true, "description": "A dimension id from GET /categories.", "schema": { "type": "string" }, "example": "industry" }, { "$ref": "#/components/parameters/CategoryEntity" }, { "name": "q", "in": "query", "description": "Prefix search on the value. Lead with * to search anywhere in it.", "required": false, "schema": { "type": "string" } }, { "name": "top", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500 } }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "counts", "in": "query", "description": "false skips the counting and is cheaper.", "required": false, "schema": { "type": "boolean", "default": true } }, { "$ref": "#/components/parameters/DimIndustry" }, { "$ref": "#/components/parameters/DimCountry" }, { "$ref": "#/components/parameters/DimRegion" }, { "$ref": "#/components/parameters/DimCity" }, { "$ref": "#/components/parameters/DimStage" }, { "$ref": "#/components/parameters/DimInvestorType" }, { "$ref": "#/components/parameters/DimInvestmentStage" } ], "responses": { "200": { "description": "The values.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "dimension": { "type": "string" }, "entity": { "type": "string" }, "narrowedBy": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryValue" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/categories/{dimension}/{value}/{entity}": { "get": { "tags": [ "Categories" ], "operationId": "listCategoryEntities", "summary": "The entities in a category", "description": "This is `/startups`, `/funds` or `/startups/fundingrounds` with the category conditions applied - the same query, so `$select`, `$expand`, `$orderby`, `$filter` and paging behave exactly as they do there. Extra dimensions on the query string stack with the one in the path.\n\nAny dimension id may also be passed as a query parameter to narrow the set before counting - `?country=Germany&industry=fintech`. OpenAPI cannot express an open set of parameter names, so only the most used ones are declared below; the full list is at `GET /categories`. Values may be comma separated, and closed dimensions accept the label, the slug or the member name (\"Series A\" = \"series-a\" = \"SeriesA\").", "parameters": [ { "name": "dimension", "in": "path", "required": true, "schema": { "type": "string" }, "example": "industry" }, { "name": "value", "in": "path", "required": true, "schema": { "type": "string" }, "example": "fintech" }, { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "startups", "funds", "rounds" ] } }, { "$ref": "#/components/parameters/Top" }, { "$ref": "#/components/parameters/Skip" }, { "$ref": "#/components/parameters/Filter" }, { "$ref": "#/components/parameters/Select" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/Count" }, { "$ref": "#/components/parameters/DimIndustry" }, { "$ref": "#/components/parameters/DimCountry" }, { "$ref": "#/components/parameters/DimRegion" }, { "$ref": "#/components/parameters/DimCity" }, { "$ref": "#/components/parameters/DimStage" }, { "$ref": "#/components/parameters/DimInvestorType" }, { "$ref": "#/components/parameters/DimInvestmentStage" } ], "responses": { "200": { "description": "The entities, shaped as the underlying collection returns them.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/signals/types": { "get": { "tags": [ "Signals" ], "operationId": "listSignalTypes", "summary": "What can be watched, and what each type means", "description": "Static. Read it before subscribing so type names are never guessed at.", "parameters": [], "responses": { "200": { "description": "The catalogue.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "clock": { "type": "object", "description": "A reminder of which of the two timestamps the feed is ordered by." }, "types": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "object": { "type": "string", "nullable": true }, "carriesAmount": { "type": "boolean" }, "description": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/signals": { "get": { "tags": [ "Signals" ], "operationId": "listSignals", "summary": "The change feed", "description": "Everything that moved: rounds recorded, investors attached to them, portfolios and valuations updated, companies and funds appearing and changing, people joining teams, press mentions.\n\n**Ordered and paged by `detectedAt`, when this database recorded the change - never by `occurredAt`, the market date.** Venture news arrives late and out of order: a round announced three weeks ago is recorded today, and a consumer polling on the market date would never see it. `occurredAt` is filterable and is the right field to display, but it cannot be the cursor.\n\nTo follow the feed: call with `order=asc`, keep `nextCursor`, pass it back next time. Signal ids are deterministic, so re-reading an overlapping window is safe to deduplicate on `id`. Polling more than hourly wastes credits - the crawlers do not produce change faster than that.\n\nAny dimension id may also be passed as a query parameter to narrow the set before counting - `?country=Germany&industry=fintech`. OpenAPI cannot express an open set of parameter names, so only the most used ones are declared below; the full list is at `GET /categories`. Values may be comma separated, and closed dimensions accept the label, the slug or the member name (\"Series A\" = \"series-a\" = \"SeriesA\").", "parameters": [ { "name": "types", "in": "query", "description": "Comma separated, from GET /signals/types. Narrowing this is the single biggest cost saving.", "required": false, "schema": { "type": "string" }, "example": "round.recorded,investor.joined_round" }, { "name": "since", "in": "query", "description": "Lower bound on detectedAt. ISO date or timestamp.", "required": false, "schema": { "type": "string" } }, { "name": "until", "in": "query", "description": "Upper bound on detectedAt.", "required": false, "schema": { "type": "string" } }, { "name": "occurredSince", "in": "query", "description": "Lower bound on the market date.", "required": false, "schema": { "type": "string" } }, { "name": "occurredUntil", "in": "query", "description": "Upper bound on the market date.", "required": false, "schema": { "type": "string" } }, { "name": "subject", "in": "query", "description": "Company or fund ids, comma separated. How you watch a portfolio.", "required": false, "schema": { "type": "string" } }, { "name": "minAmount", "in": "query", "description": "USD. Excludes the types that carry no amount at all.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "nextCursor from the previous page. Opaque; never expires.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "asc to follow the feed forward, desc to browse recent history.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "expand", "in": "query", "description": "subject, object, or both - adds names and saves a lookup per row.", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/DimIndustry" }, { "$ref": "#/components/parameters/DimCountry" }, { "$ref": "#/components/parameters/DimRegion" }, { "$ref": "#/components/parameters/DimCity" }, { "$ref": "#/components/parameters/DimStage" }, { "$ref": "#/components/parameters/DimInvestorType" }, { "$ref": "#/components/parameters/DimInvestmentStage" } ], "responses": { "200": { "description": "A page of signals.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/pricing": { "get": { "tags": [ "Pricing" ], "operationId": "getPricing", "summary": "The rate card", "description": "What every endpoint costs, so a job can be budgeted before it is run rather than discovered by being charged. Free, and answered even when the caller is out of credits - quoting a price must never cost anything, least of all then.\n\nPair it with `$count`, which reports how many records match a filter for one credit: multiply the two and you have the bill.", "parameters": [], "responses": { "200": { "description": "The current rate card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Preferred. The key looks like `pk_live_...`." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "The same key, sent as `Authorization: Bearer pk_live_...`. Legacy RSA tokens are accepted here too." } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Top": { "name": "$top", "in": "query", "description": "How many records to return, and therefore what the request costs on the record-priced collections. Defaults to 25. The ceiling is the plan's: 100 on Free, up to 5,000 on Enterprise.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 25 } }, "Skip": { "name": "$skip", "in": "query", "description": "How many rows to skip; use with `$top` to page.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "Filter": { "name": "$filter", "in": "query", "description": "OData style filter, e.g. `Location eq 'Berlin'` or `Founded ge 2020`. Combine with `and` / `or`.", "schema": { "type": "string" }, "example": "Location eq 'Berlin' and Founded ge 2020" }, "Select": { "name": "$select", "in": "query", "description": "Comma separated field list. Asking for fewer fields makes responses smaller and easier to read.", "schema": { "type": "string" }, "example": "Id,Name,Website,Location" }, "OrderBy": { "name": "$orderby", "in": "query", "description": "Field, optionally followed by `desc`.", "schema": { "type": "string" }, "example": "TotalRaised desc" }, "Count": { "name": "$count", "in": "query", "description": "Return the number of matches instead of the rows.", "schema": { "type": "boolean" } }, "CategoryEntity": { "name": "entity", "in": "query", "description": "Which collection to count over. Defaults to startups.", "required": false, "schema": { "type": "string", "enum": [ "startups", "funds", "rounds" ], "default": "startups" } }, "DimIndustry": { "name": "industry", "in": "query", "description": "Industry tag, e.g. `fintech`. Comma separated for several values.", "required": false, "schema": { "type": "string" } }, "DimCountry": { "name": "country", "in": "query", "description": "Country of a registered address, e.g. `Germany`. Comma separated for several values.", "required": false, "schema": { "type": "string" } }, "DimRegion": { "name": "region", "in": "query", "description": "State, province or region of a registered address. Comma separated for several values.", "required": false, "schema": { "type": "string" } }, "DimCity": { "name": "city", "in": "query", "description": "City of a registered address. Comma separated for several values.", "required": false, "schema": { "type": "string" } }, "DimStage": { "name": "stage", "in": "query", "description": "Series of the latest confirmed round, e.g. `series-a`. Startups only. Comma separated for several values.", "required": false, "schema": { "type": "string" } }, "DimInvestorType": { "name": "investor_type", "in": "query", "description": "Kind of investor, e.g. `venture-capital`. Funds only. Comma separated for several values.", "required": false, "schema": { "type": "string" } }, "DimInvestmentStage": { "name": "investment_stage", "in": "query", "description": "Stage a fund invests at. Funds only. Comma separated for several values.", "required": false, "schema": { "type": "string" } } }, "headers": { "XRateLimitLimit": { "description": "Free requests included this month.", "schema": { "type": "integer" } }, "XRateLimitRemaining": { "description": "Requests left, including any purchased balance.", "schema": { "type": "integer" } }, "XRateLimitReset": { "description": "Unix time when the monthly allowance refills.", "schema": { "type": "integer" } }, "XCreditsCharged": { "description": "Credits this request actually cost, after the response was measured. Absent when it cost nothing.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "The request was malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "No key, or the key is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key is valid but not entitled to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "QuotaExceeded": { "description": "Monthly credits are spent. This is not a permissions problem and retrying will not help: either buy credits or wait for the reset. `Retry-After` gives the seconds until then.", "headers": { "Retry-After": { "description": "Seconds until the allowance refills.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaError" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string", "description": "Human readable." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine readable code." }, "message": { "type": "string" } } } } }, "QuotaError": { "type": "object", "properties": { "status": { "type": "string", "example": "429 (TooManyRequests)" }, "message": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "credits_exhausted" }, "message": { "type": "string" } } }, "credits": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "reset": { "type": "string", "format": "date-time" }, "required": { "type": "integer", "description": "Credits this request needed. Compare with remaining: if the gap is the page size, retry with a smaller $top." }, "plan": { "type": "string" }, "overage_used": { "type": "integer" }, "overage_cap": { "type": "integer" } } }, "actions": { "type": "array", "description": "What can be done about it. Check required against remaining before anything else - a smaller $top may well get through.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "purchase_credits", "raise_overage_cap", "reduce_page_size", "wait" ] }, "url": { "type": "string" }, "contact": { "type": "string", "description": "For raise_overage_cap: the address that can move the cap. It is not self-service." }, "until": { "type": "string", "format": "date-time" }, "parameter": { "type": "string", "description": "For reduce_page_size: the parameter to lower." } } } }, "docs_url": { "type": "string" } } }, "Credits": { "type": "object", "properties": { "MonthlyGrant": { "type": "integer", "description": "Credits included in the plan each calendar month." }, "GrantUsed": { "type": "integer" }, "GrantRemaining": { "type": "integer" }, "Balance": { "type": "integer", "description": "Purchased credits. These do not expire with the month." }, "Remaining": { "type": "integer", "description": "Grant plus balance." }, "LifetimeUsed": { "type": "integer" }, "PeriodStart": { "type": "string", "format": "date" }, "ResetAt": { "type": "string", "format": "date-time" }, "PlanCode": { "type": "string", "example": "growth" }, "PlanTitle": { "type": "string", "example": "Growth" }, "OverageUsed": { "type": "integer", "description": "Credits spent past the grant and the balance this period, billed on actual use." }, "OverageCap": { "type": "integer", "description": "Ceiling on that. Zero means the plan has no overage and stops at nil." }, "OverageRate": { "type": "number", "description": "Dollars per overage credit." }, "OverageAmountDue": { "type": "number", "description": "What the overage accrued so far comes to, in dollars." } } }, "CompanyMatch": { "type": "object", "description": "A lightweight search hit. Use `Id` to fetch the full record.", "properties": { "Id": { "type": "string", "format": "uuid" }, "Name": { "type": "string" }, "Website": { "type": "string" }, "Domain": { "type": "string" }, "Logo": { "type": "string" } } }, "Fund": { "type": "object", "description": "A venture fund. Which fields come back depends on `$select`.", "properties": { "Id": { "type": "string", "format": "uuid" }, "Name": { "type": "string" }, "Description": { "type": "string" }, "OneLine": { "type": "string" }, "Website": { "type": "string" }, "Domain": { "type": "string" }, "Logo": { "type": "string" }, "Location": { "type": "string" }, "Headquarters": { "type": "string" }, "Founded": { "type": "integer", "nullable": true }, "MembersCount": { "type": "string", "nullable": true, "description": "A band, not an exact number." }, "PortfolioCount": { "type": "integer", "nullable": true }, "Keywords": { "type": "string" }, "Tags": { "type": "array", "items": { "type": "string" } }, "InvestmentTypes": { "type": "array", "items": { "type": "string" } }, "InvestmentStages": { "type": "array", "items": { "type": "string" } }, "OperatingStatus": { "type": "string" }, "LastActivity": { "type": "string", "format": "date-time", "nullable": true }, "Twitter": { "type": "string" }, "LinkedIn": { "type": "string" }, "Facebook": { "type": "string" }, "Email": { "type": "string" }, "Phone": { "type": "string" } } }, "Startup": { "type": "object", "description": "A company. Which fields come back depends on `$select`.", "properties": { "Id": { "type": "string", "format": "uuid" }, "Name": { "type": "string" }, "Description": { "type": "string" }, "OneLine": { "type": "string" }, "Website": { "type": "string" }, "Domain": { "type": "string" }, "Logo": { "type": "string" }, "Location": { "type": "string" }, "Founded": { "type": "integer", "nullable": true }, "MembersCount": { "type": "string", "nullable": true }, "TotalRaised": { "type": "integer", "format": "int64", "nullable": true, "description": "In US dollars." }, "LastFundingStage": { "type": "string", "nullable": true }, "NextFundingStage": { "type": "string", "nullable": true }, "Keywords": { "type": "string" }, "Tags": { "type": "array", "items": { "type": "string" } }, "LastActivity": { "type": "string", "format": "date-time", "nullable": true }, "Twitter": { "type": "string" }, "LinkedIn": { "type": "string" }, "Facebook": { "type": "string" }, "Email": { "type": "string" }, "Phone": { "type": "string" } } }, "Person": { "type": "object", "properties": { "Id": { "type": "string", "format": "uuid" }, "FirstName": { "type": "string" }, "LastName": { "type": "string" }, "Headline": { "type": "string" }, "Summary": { "type": "string" }, "Location": { "type": "string" }, "LinkedIn": { "type": "string" }, "Twitter": { "type": "string" }, "Facebook": { "type": "string" }, "Email": { "type": "string" } } }, "FundingRound": { "type": "object", "properties": { "Id": { "type": "string", "format": "uuid" }, "Amount": { "type": "integer", "format": "int64", "description": "In US dollars." }, "Series": { "type": "string", "description": "Seed, Series A, and so on." }, "Date": { "type": "string", "format": "date-time", "nullable": true }, "Confirmed": { "type": "boolean" }, "Entities": { "type": "array", "description": "Who took part: the company raising and the investors.", "items": { "type": "object", "additionalProperties": true } } } }, "NewsItem": { "type": "object", "properties": { "Id": { "type": "string", "format": "uuid" }, "EntityId": { "type": "string", "format": "uuid", "description": "The company the item is about." }, "Title": { "type": "string" }, "Description": { "type": "string" }, "Summary": { "type": "string" }, "Category": { "type": "string" }, "Author": { "type": "string" }, "Date": { "type": "string", "format": "date-time", "nullable": true }, "CreatedTimeStamp": { "type": "string", "format": "date-time" } } }, "CategoryValue": { "type": "object", "description": "One value on one axis.", "properties": { "value": { "type": "string", "description": "What to send back in a filter.", "example": "series-a" }, "label": { "type": "string", "description": "What to show a person.", "example": "Series A" }, "count": { "type": "integer", "nullable": true, "description": "Entities carrying this value; absent when counts=false." } } }, "CategoryDimension": { "type": "object", "description": "One axis the data can be sliced along.", "properties": { "id": { "type": "string", "example": "industry" }, "title": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string", "enum": [ "open", "closed", "bucketed" ], "description": "closed dimensions carry their whole value list here; open ones must be listed from the API." }, "entities": { "type": "array", "items": { "type": "string" } }, "filterField": { "type": "string", "description": "The $filter field name on the entity collections, if you would rather query them directly." }, "values": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/CategoryValue" } } } }, "SignalEntity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "startup", "fund", "round", "news", "person", "valuation" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Only when expand includes this side." }, "website": { "type": "string" }, "domain": { "type": "string" } } }, "Signal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Derived from the change itself, not from when it was read. Stable across calls, so an overlapping window is safe to deduplicate." }, "type": { "type": "string", "example": "round.recorded", "description": "One of the types listed by GET /signals/types." }, "detectedAt": { "type": "string", "format": "date-time", "description": "When this database recorded the change. The feed is ordered and paged by this." }, "occurredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When it happened in the market. The date to display; never the cursor." }, "subject": { "$ref": "#/components/schemas/SignalEntity" }, "object": { "allOf": [ { "$ref": "#/components/schemas/SignalEntity" } ], "nullable": true }, "amount": { "type": "integer", "format": "int64", "nullable": true, "description": "USD, normalised. Present only for the types that carry money." }, "label": { "type": "string", "nullable": true, "description": "A short human string: the series, the exit status." } } }, "SignalPage": { "type": "object", "properties": { "signals": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass back as ?cursor= to continue. Never expires. Store this, not a timestamp." }, "hasMore": { "type": "boolean" }, "order": { "type": "string", "enum": [ "asc", "desc" ] } } }, "PriceList": { "type": "object", "properties": { "unit": { "type": "string", "example": "credit" }, "formula": { "type": "string", "example": "credits = max(1, ceil(base + records * credits_per_record * (1 + 0.25 * expands)))" }, "notes": { "type": "array", "items": { "type": "string" } }, "plans": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "growth" }, "title": { "type": "string" }, "monthly_price_usd": { "type": "number", "example": 79 }, "monthly_credits": { "type": "integer", "example": 15000 }, "price_per_credit_usd": { "type": "number", "example": 0.0052 }, "overage_price_per_credit_usd": { "type": "number", "example": 0.007 }, "overage_credits_allowed": { "type": "integer" }, "max_page_size": { "type": "integer", "example": 1000 } } } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "example": "profile" }, "base_credits": { "type": "number" }, "credits_per_record": { "type": "number", "example": 1 }, "description": { "type": "string" } } } }, "endpoints": { "type": "array", "description": "Every endpoint and its weights.", "items": { "type": "object", "properties": { "endpoint": { "type": "string", "example": "GET v2/startups", "description": "Verb and route template, the same key usage is reported under." }, "group": { "type": "string" }, "base_credits": { "type": "number" }, "credits_per_record": { "type": "number" }, "default_page_size": { "type": "integer" }, "max_page_size": { "type": "integer" } } } }, "dumps": { "type": "array", "description": "Flat price of each bulk dataset.", "items": { "type": "object", "properties": { "resource": { "type": "string" }, "credits": { "type": "integer" } } } }, "docs_url": { "type": "string" } } } } } }