# Dealroom API

## Docs

- [SKILL](https://developers.beta.dealroom.co/.codex/skills/adding-new-data/SKILL.md): End-to-end workflow for any database schema change. Covers BigQuery discovery, Drizzle schema, migrations, data-loader pipeline, API types, response shaping, OpenAPI docs, and tests. Use when adding a new column, exposing a DB field in an API response, backfilling data from BigQuery, adding a new ta…
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/address-pr-comments/SKILL.md): Address GitHub PR review comments — read feedback, implement fixes, and resolve threads. Use when the user asks to go through PR feedback, fix review comments, handle code review suggestions, respond to bot comments, or clean up unresolved threads on a pull request.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/aggregations-from-sql/SKILL.md): Translate SQL analytics queries into API aggregate capabilities. Use when given SQL queries to support, adding new dimensions/filters/metrics to the aggregate endpoint, or expanding aggregate API coverage.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/breaking-api-change/SKILL.md): End-to-end workflow for introducing a breaking API change with date-based versioning. Covers transform creation, changelog generation, resource definition updates, Zod schema changes, tests, and documentation. Use when renaming a field, removing a field, restructuring a response, or adding a behavio…
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/contributing-to-public-docs/SKILL.md): Contribute to Dealroom's public developer documentation (Mintlify). Use when asked to add, update, or fix anything under `mintlify/` — guides, concepts, examples, API reference pages, changelog entries. Covers MDX, Mintlify components, variables, preview workflow, and PR conventions. Trigger on requ…
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/database-doctor/SKILL.md): Diagnose and fix AlloyDB index health — stg_ leftovers, missing indexes, stale PKs, columnar engine status. Use when queries are slow, after a data-loader run, or when the DB seems unhealthy.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/debug-deployment/SKILL.md): Inspect and debug ArgoCD deployments in staging and production. Use when pods are failing, deploys are stuck, or you need to check application health.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/design-system/SKILL.md): Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/developing-api-filters/SKILL.md): End-to-end workflow for adding, modifying, removing, or deprecating API filters. Covers data verification, filter type selection, implementation patterns, aggregate config, unit tests, benchmarks, and documentation. Use when adding a new filter, removing or deprecating a filter, modifying filter beh…
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/excalidraw-architecture/SKILL.md): Generate an Excalidraw architecture diagram of the Dealroom platform. Reads codebase structure, routes, services, schema, and pipeline to produce a live-updated docs/architecture.excalidraw file.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/fix-ci/SKILL.md): Diagnose and fix CI failures on GitHub PRs. Use when checks fail, GitHub Actions jobs fail, or the user asks to fix CI.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/fix-sonarcloud-issues/SKILL.md): Fetch and fix SonarCloud issues and quality gate failures for the dealroom-next-gen project. Can target all open issues, PR-specific issues, or branch-specific issues.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/load-testing/SKILL.md): Create and maintain k6 load tests, benchmarks, smoke tests, and validation scenarios. Use when writing k6 scripts, defining load profiles, running benchmarks against API endpoints, or analyzing performance results under server/bench/.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/local-dev-with-api/SKILL.md): How to use the Dealroom API (local dev or deployed). Use when building features that fetch entity, funding, valuation, taxonomy, or aggregate data from the Dealroom backend. Covers all endpoints, filtering, pagination, sorting, response shapes, and error handling. Use this skill whenever the user me…
- [Aggregates](https://developers.beta.dealroom.co/.codex/skills/local-dev-with-api/references/aggregates.md)
- [Ecosystems](https://developers.beta.dealroom.co/.codex/skills/local-dev-with-api/references/ecosystems.md)
- [Examples](https://developers.beta.dealroom.co/.codex/skills/local-dev-with-api/references/examples.md)
- [Filters](https://developers.beta.dealroom.co/.codex/skills/local-dev-with-api/references/filters.md)
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/project-setup/SKILL.md): First-time project setup — install prerequisites, configure env files, connect to the database, run migrations, load data, and verify everything works. Use when onboarding or when `deno task doctor` reports issues.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/reading-alloydb-metrics/SKILL.md): Read AlloyDB metrics via the Cloud Monitoring REST API — CPU utilization, memory, connections, query latency. Use when checking database performance, investigating slow queries, monitoring after deployments, or analyzing load test impact on the database.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/resolving-conflicts/SKILL.md): Resolve merge conflicts when syncing, merging, or rebasing a feature branch with main.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/squash-commits/SKILL.md): Squash all commits in current branch into a single commit. Use when a PR branch has too many commits.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/worktree/SKILL.md): Manage git worktrees for parallel feature development. Use when creating, listing, removing, or cleaning up worktrees, switching between branches in a bare repo setup, or initializing the worktree structure.
- [SKILL](https://developers.beta.dealroom.co/.codex/skills/write-interaction-tests/SKILL.md): Write Storybook interaction tests (play functions) for dealroom-nexus components. Reads component source for props/API, then adds play functions to stories with assertions. Use when adding interaction tests, testing component behavior, or writing play functions.
- [CLAUDE](https://developers.beta.dealroom.co/CLAUDE.md)
- [Aggregate data by source with structured filter syntax](https://developers.beta.dealroom.co/api-reference/aggregate/aggregate-data-by-source-with-structured-filter-syntax.md): Query a specific source (founders, investors, companies, funding-rounds, valuations) with structured filter syntax.
- [Multiple metrics with per-metric filters in a single query](https://developers.beta.dealroom.co/api-reference/aggregate/multiple-metrics-with-per-metric-filters-in-a-single-query.md): Return multiple labeled metrics from a single SQL query, each with optional per-metric filters using aggregate FILTER (WHERE ...) clauses. Supports all metric types (COUNT, SUM, AVG, MEDIAN, MAX) and optional dimensional grouping (group_by).
- [Create a new API key](https://developers.beta.dealroom.co/api-reference/api-keys/create-a-new-api-key.md): Provisions an Auth0 application and returns the client credentials.
- [Get API key details](https://developers.beta.dealroom.co/api-reference/api-keys/get-api-key-details.md): Returns metadata for an API key — name, type (`m2m` or `application`), the granted permission set, `client_id`, last-used timestamp, and allowed origins / callbacks for application keys. Never returns the `client_secret` (only available at creation time). Requires the `read:api-keys` scope.
- [List API keys](https://developers.beta.dealroom.co/api-reference/api-keys/list-api-keys.md): Returns all active API keys for the authenticated user. Users with the `admin:api-keys` permission see all keys across the organization. Secrets are never returned.
- [Revoke an API key](https://developers.beta.dealroom.co/api-reference/api-keys/revoke-an-api-key.md): Deactivates the API key and deletes the Auth0 M2M application.
- [Return the authenticated user's decoded token claims](https://developers.beta.dealroom.co/api-reference/auth/return-the-authenticated-users-decoded-token-claims.md): Useful for verifying that your JWT contains the expected roles, permissions, and custom claims.
- [Create a new ecosystem](https://developers.beta.dealroom.co/api-reference/ecosystems/create-a-new-ecosystem.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — Persists to the user-owned `ecosystems` table. No BigQuery source feeds this table.
- [Get ecosystem by ID or slug](https://developers.beta.dealroom.co/api-reference/ecosystems/get-ecosystem-by-id-or-slug.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — Backed by the same user-owned `ecosystems` table — IDs only exist after a POST.
- [List all active ecosystems](https://developers.beta.dealroom.co/api-reference/ecosystems/list-all-active-ecosystems.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — The `ecosystems` table is user-owned and not populated by the BigQuery loader. Fresh deployments return an empty list until ecosystems are created via POST.
- [Soft-delete an ecosystem (set is_active=false)](https://developers.beta.dealroom.co/api-reference/ecosystems/soft-delete-an-ecosystem-set-is_active=false.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — Soft-deletes a row in the user-owned `ecosystems` table.
- [Update an existing ecosystem](https://developers.beta.dealroom.co/api-reference/ecosystems/update-an-existing-ecosystem.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — Updates the user-owned `ecosystems` table. Changes do not sync to BigQuery and may be lost on full reseed.
- [Get changelog for a specific entity](https://developers.beta.dealroom.co/api-reference/entities/get-changelog-for-a-specific-entity.md): Returns the change history for an entity, showing what fields changed over time with previous and current values. **Temporarily disabled while the upstream dbt deltas pipeline is broken — returns 503.**
- [Get single entity by ID or UUID](https://developers.beta.dealroom.co/api-reference/entities/get-single-entity-by-id-or-uuid.md): Returns the full entity record by numeric ID or stable UUID. The response shape varies by entity type — companies, funds, people, and universities each expose an optional sub-object (`company`, `fund`, `person`, `university`) alongside the shared base fields. Monetary fields convert to the requested…
- [Get valuations for a specific entity](https://developers.beta.dealroom.co/api-reference/entities/get-valuations-for-a-specific-entity.md): Returns the valuation history (one row per recorded year/month) for a company. Use `/api/valuations` for the cross-entity list endpoint.
- [Get yearly financials for a specific entity](https://developers.beta.dealroom.co/api-reference/entities/get-yearly-financials-for-a-specific-entity.md): Returns one row per recorded year of revenue, EBITDA, valuation, and employee count for the entity. Years with no revenue or EBITDA data are excluded. Monetary values are strings to preserve precision and are converted to the requested currency when `?currency=` is provided (defaults to USD).
- [List entities with filters](https://developers.beta.dealroom.co/api-reference/entities/list-entities-with-filters.md): Returns a paginated list of entities — the unified index across companies, funds, people, and universities. Filter by 90+ keys (funding, location, sector, status, etc.), sort by any indexed field, and page through results. Monetary fields are converted to the requested `?currency=` (default USD).
- [List entity geo points for map rendering](https://developers.beta.dealroom.co/api-reference/entities/list-entity-geo-points-for-map-rendering.md): Lightweight endpoint returning only id, name, lat, lon, country, and city. Supports the same filters as the entity list but with higher limits (up to 5000) and minimal payload.
- [Discover available filters](https://developers.beta.dealroom.co/api-reference/filters/discover-available-filters.md): Returns available filters for the given scope with category grouping, operators, and optional user-facing descriptions and examples. Valid scopes: companies, investors, transactions, people, universities, news.
- [List filter values](https://developers.beta.dealroom.co/api-reference/filters/list-filter-values.md): Returns values for a filter with entity counts. Supports fuzzy search, pagination, and optional metadata enrichment. Only filters with type id_lookup or enum have values.
- [Search filters and values](https://developers.beta.dealroom.co/api-reference/filters/search-filters-and-values.md): Returns the picker-ready search result set for one scope: year-intent matches, value matches across every searchable dimension, and filter-name/description matches. Single round-trip replacement for the client-side fan-out across `/api/filters/:key/values`.
- [Get single founder by ID or UUID](https://developers.beta.dealroom.co/api-reference/founders/get-single-founder-by-id-or-uuid.md): Returns the full founder profile by numeric ID or stable UUID. Includes biographic details, founder badges (super founder, serial founder, etc.), professional history, education, and links to founded companies.
- [List founders with filters](https://developers.beta.dealroom.co/api-reference/founders/list-founders-with-filters.md): Returns a paginated list of founders (entities with is_founder=true) with company associations, education history, and professional backgrounds. Supports the same filter syntax as other endpoints.
- [Funding funnel — capital-phase distribution](https://developers.beta.dealroom.co/api-reference/funding-analytics/funding-funnel-—-capital-phase-distribution.md): Cross-tabulates companies by total capital raised (9 buckets) against a chosen dimension.
- [Funding heatmap — 2D cross-tabulation](https://developers.beta.dealroom.co/api-reference/funding-analytics/funding-heatmap-—-2d-cross-tabulation.md): Returns a 2D matrix of funding data grouped by two configurable dimensions.
- [Round transitions — stage progression analysis](https://developers.beta.dealroom.co/api-reference/funding-analytics/round-transitions-—-stage-progression-analysis.md): Analyzes how companies move between funding stages over time.
- [Health check endpoint](https://developers.beta.dealroom.co/api-reference/health/health-check-endpoint.md): Public liveness probe. Returns `200` when the API can reach the database, `503` otherwise. No authentication required — safe to use from uptime monitors and load-balancer health checks.
- [Observability info endpoint (auth-protected)](https://developers.beta.dealroom.co/api-reference/health/observability-info-endpoint-auth-protected.md): > ⚠ **STUB ENDPOINT** — Returns the server's observability configuration (OTEL endpoint, instrumentation list). It is NOT a metric data source — use Prometheus / Grafana or `/api/usage/*` for measurements.
- [Get single investor by ID or UUID](https://developers.beta.dealroom.co/api-reference/investors/get-single-investor-by-id-or-uuid.md): Returns the full investor profile by numeric ID or stable UUID. Includes investor type, stages, deal-size ranges, portfolio summary (top companies, total rounds, total invested), and the underlying entity record. Monetary fields convert to the requested `?currency=`.
- [List investors with filters](https://developers.beta.dealroom.co/api-reference/investors/list-investors-with-filters.md): Returns a paginated list of investors (VCs, corporates, angels, etc.) with optional filters and sorting. All entities with is_investor=true are included. Use portfolio_count_tag and/or portfolio_count_location to compute a portfolio match count (number of investments matching specified tags/location…
- [Create a landscape in an ecosystem](https://developers.beta.dealroom.co/api-reference/landscapes/create-a-landscape-in-an-ecosystem.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — Persists to the user-owned `landscapes` table.
- [Delete a landscape and its entity links](https://developers.beta.dealroom.co/api-reference/landscapes/delete-a-landscape-and-its-entity-links.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — Hard-deletes a row in the user-owned `landscapes` table.
- [List landscapes for an ecosystem](https://developers.beta.dealroom.co/api-reference/landscapes/list-landscapes-for-an-ecosystem.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — The `landscapes` and `landscape_entities` tables are user-owned and not populated by the BigQuery loader.
- [Set entity list for a landscape (replace all)](https://developers.beta.dealroom.co/api-reference/landscapes/set-entity-list-for-a-landscape-replace-all.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — Rewrites `landscape_entities` for a landscape that only exists in this environment.
- [Update landscape metadata](https://developers.beta.dealroom.co/api-reference/landscapes/update-landscape-metadata.md): > ⚠ **TABLE NOT LOADED FROM BIGQUERY** — Updates the user-owned `landscapes` table.
- [Get single news article by ID](https://developers.beta.dealroom.co/api-reference/news/get-single-news-article-by-id.md): Returns one news article by ID, including its body excerpt, source, publish date, type, monetary amount (for deal articles, converted to the requested `?currency=`), and any linked Dealroom entities.
- [List news articles with filters](https://developers.beta.dealroom.co/api-reference/news/list-news-articles-with-filters.md): Returns a paginated list of published news articles. Articles can be about deals (VC rounds, IPOs, M&A), insights, events, partnerships, and more. Supports filtering by source, article type, sector, entity, and date range.
- [Search companies and investors by name](https://developers.beta.dealroom.co/api-reference/search/search-companies-and-investors-by-name.md): Fuzzy name search across companies and investors using trigram similarity. Returns up to `limit` results per category, ranked by relevance.
- [Cancel invitation](https://developers.beta.dealroom.co/api-reference/teams/cancel-invitation.md): Revokes a pending team invitation by ID. The invitee can no longer redeem the invite token. Has no effect on members who have already accepted. Requires the `manage:team-members` scope.
- [Create a new team](https://developers.beta.dealroom.co/api-reference/teams/create-a-new-team.md): Creates a team and adds the authenticated user as the owner.
- [Create invitation](https://developers.beta.dealroom.co/api-reference/teams/create-invitation.md): Invite a user to the team by email or user ID. Token-based — the frontend handles delivery.
- [Delete team](https://developers.beta.dealroom.co/api-reference/teams/delete-team.md): Soft-deletes the team. Requires owner role.
- [Get team details](https://developers.beta.dealroom.co/api-reference/teams/get-team-details.md): Returns team metadata: name, owner, created/updated timestamps, and the caller's role within the team. For the member list, call `/api/teams/{id}/members`. Requires the `read:teams` scope.
- [List pending invitations](https://developers.beta.dealroom.co/api-reference/teams/list-pending-invitations.md): Returns all pending invitations for the team. Requires owner or admin role.
- [List team members](https://developers.beta.dealroom.co/api-reference/teams/list-team-members.md): Returns every confirmed member of the team along with their role (`owner`, `admin`, `member`) and the timestamp they joined. Pending invitations are surfaced separately via `/api/teams/{id}/invitations`. Requires the `read:teams` scope.
- [List user's teams](https://developers.beta.dealroom.co/api-reference/teams/list-users-teams.md): Returns all active teams the authenticated user is a member of.
- [Remove team member](https://developers.beta.dealroom.co/api-reference/teams/remove-team-member.md): Remove a member from the team. Owner/admin can remove others; any member can remove themselves.
- [Respond to an invitation](https://developers.beta.dealroom.co/api-reference/teams/respond-to-an-invitation.md): Accept or decline a team invitation by setting its status.
- [Update member role](https://developers.beta.dealroom.co/api-reference/teams/update-member-role.md): Change a team member's role. Requires owner or admin role.
- [Update team](https://developers.beta.dealroom.co/api-reference/teams/update-team.md): Update team name and/or slug. Requires owner or admin role.
- [Timeseries — yearly metric aggregation](https://developers.beta.dealroom.co/api-reference/timeseries/timeseries-—-yearly-metric-aggregation.md): Returns aggregated yearly values for a single metric across filtered entities.
- [Get transactions for a specific entity](https://developers.beta.dealroom.co/api-reference/transactions/get-transactions-for-a-specific-entity.md): Lists all funding-related transactions for an entity. Entity funding_summary remains funding-round based.
- [List transactions with filters](https://developers.beta.dealroom.co/api-reference/transactions/list-transactions-with-filters.md): Lists company funding-related transactions (rounds, equity events, debt, grants). Supports the structured filter expression syntax shared with `/api/entities` and the same `limit` / `offset` / `sort` / `include_total` pagination model.
- [Get aggregated usage summary](https://developers.beta.dealroom.co/api-reference/usage/get-aggregated-usage-summary.md): Returns total request and error counts per endpoint for the given date range. M2M tokens see their own usage only. Admins can specify a `client_id` to query any client.
- [Get usage timeseries](https://developers.beta.dealroom.co/api-reference/usage/get-usage-timeseries.md): Returns time-bucketed usage data for charts. Supports hourly and daily granularity. Daily aggregates hourly rows at query time via date_trunc.
- [List valuations with filters](https://developers.beta.dealroom.co/api-reference/valuations/list-valuations-with-filters.md): Returns the cross-entity valuation history. Each row is one company's recorded valuation at a specific year/month, with the valuation source where available. Use `/api/entities/:id/valuations` for a single-entity view.
- [Model Context Protocol (MCP)](https://developers.beta.dealroom.co/mintlify/agent-apis/mcp.md): Connect AI agents to Dealroom data through the Dealroom MCP server. Install in Cursor, Claude Desktop, or any MCP-compatible client.
- [Changelog](https://developers.beta.dealroom.co/mintlify/changelog.md): Breaking changes, deprecations, and new features across API versions.
- [Aggregates](https://developers.beta.dealroom.co/mintlify/concepts/aggregates.md): Compute counts, sums, medians, and percentiles grouped by one or more dimensions via the Dealroom aggregate endpoints — heatmaps, top-N rankings, timeseries, and funnels in one API call.
- [Errors](https://developers.beta.dealroom.co/mintlify/concepts/errors.md): How the Dealroom API surfaces errors — response envelope, canonical error-code catalog, and common scenarios with example responses.
- [Filtering](https://developers.beta.dealroom.co/mintlify/concepts/filtering.md): Narrow Dealroom API results with filter expressions. Supports comparison operators, logical AND/OR, and 90+ fields across entities.
- [Known limitations](https://developers.beta.dealroom.co/mintlify/concepts/known-limitations.md): Endpoints and filters that the Dealroom API exposes but are not fully functional today. Read before relying on them in production code.
- [Pagination](https://developers.beta.dealroom.co/mintlify/concepts/pagination.md): Use the `cursor` query parameter to walk through results, with `limit` controlling page size and `include_total` opting into a total count.
- [Rate limits](https://developers.beta.dealroom.co/mintlify/concepts/rate-limits.md): How the Dealroom API rate-limits requests, what a 429 response looks like, and how to request higher limits.
- [API versioning](https://developers.beta.dealroom.co/mintlify/concepts/versioning.md): Learn how the Dealroom API uses Stripe-style date-based versioning to handle breaking changes while keeping existing integrations stable.
- [Portfolio Dashboard](https://developers.beta.dealroom.co/mintlify/examples/portfolio-dashboard.md): Build a branded VC portfolio monitoring dashboard with React, D3, and the Dealroom API — runs entirely in the browser using Auth0 Universal Login
- [Top fintech startups](https://developers.beta.dealroom.co/mintlify/examples/top-startups.md): A 20-line recipe that fetches the 10 most-funded fintech startups via the Dealroom API. Token exchange + filter + sort + limit, in cURL, Node.js, and Python.
- [Authentication](https://developers.beta.dealroom.co/mintlify/getting-started/authentication.md): Get started in under a minute with Node.js or Python SDKs, or use raw HTTP. Create API keys, exchange credentials for Bearer tokens, and authenticate requests.
- [Quickstart](https://developers.beta.dealroom.co/mintlify/getting-started/quickstart.md): Get started with the Dealroom API in under 5 minutes. Obtain an access token, make your first request, and explore entity search results.
- [Dealroom API](https://developers.beta.dealroom.co/mintlify/index.md): Access startup, investor, and funding round data for 5M+ companies via the Dealroom REST API. Query entities, valuations, and taxonomy data programmatically.
- [Filters & Sorting](https://developers.beta.dealroom.co/mintlify/references/filters-and-sorting.md): Complete reference of available filters and sort keys for each API scope.
- [Pr conflict resolution summary](https://developers.beta.dealroom.co/pr-conflict-resolution-summary.md)

## OpenAPI Specs

- [openapi](https://developers.beta.dealroom.co/openapi.json)