Dealroom Notes API

openapi: 3.2.0
info:
  title: Dealroom Notes API
  version: '2026-10-09'
  description: REST API for the Dealroom platform — companies, funds, founders, investors, funding rounds, valuations, taxonomy, news, and aggregate analytics across all of them. Authentication uses Auth0 (Bearer JWT or OAuth2 client_credentials). All endpoints are versioned via the `API-Version` header (Stripe-style date-based versioning).
  contact:
    name: Dealroom API support
    email: support@dealroom.co
    url: https://dealroom.co
  termsOfService: https://dealroom.co/terms
  license:
    name: Proprietary — Dealroom commercial license
    url: https://dealroom.co/terms
servers:
- url: https://api.dealroom.app
  description: Production
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Notes
paths:
  /data/notes:
    get:
      operationId: listNotes
      security:
      - oauth2:
        - read:news
      - bearerAuth:
        - read:news
      tags:
      - Notes
      summary: List notes
      description: Returns a paginated list of published notes plus every news note — the full note archive (news, editorial, research, and more), a superset of `/data/news`. Supports filtering by `is_news`, `type`, `status`, and `entity_id` (notes mentioning an entity).
      parameters:
      - schema:
          type: string
          description: 'Filter expression for notes.


            Examples:

            - Single: type[eq]:public

            - AND: and(is_news[eq]:true,status[eq]:published)

            - OR: or(status[eq]:published,status[eq]:expired)


            Operators: eq, neq, gte, lte, gt, lt, in_any, nin_any

            Default ref: ''note''

            '
          example: and(is_news[eq]:true,status[eq]:published)
        required: false
        description: 'Filter expression for notes.


          Examples:

          - Single: type[eq]:public

          - AND: and(is_news[eq]:true,status[eq]:published)

          - OR: or(status[eq]:published,status[eq]:expired)


          Operators: eq, neq, gte, lte, gt, lt, in_any, nin_any

          Default ref: ''note''

          '
        name: filter
        in: query
      - schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 2000
          default: 25
          description: Number of results to return (1-2000, default 25)
          example: 25
        required: false
        description: Number of results to return (1-2000, default 25)
        name: limit
        in: query
      - schema:
          type: string
          description: Opaque cursor token from a previous response's `page.next_cursor` or `page.prev_cursor`. Round-trip it as-is — do not decode or modify.
          example: eyJ2IjoxLCJkIjoibmV4dCJ9
        required: false
        description: Opaque cursor token from a previous response's `page.next_cursor` or `page.prev_cursor`. Round-trip it as-is — do not decode or modify.
        name: cursor
        in: query
      - schema:
          type: string
          pattern: ^(?:-?\w+)?(?:,(?:-?\w+)?)*$
          description: Sort by one or more keys. Prefix with `-` for descending order; comma-separated for multi-key sorts.
          example: -published_at
        required: false
        description: Sort by one or more keys. Prefix with `-` for descending order; comma-separated for multi-key sorts.
        name: sort
        in: query
      - schema:
          type: boolean
          description: Pass `true` to compute `page.total` (the matching record count). By default no count query runs and `page.total` is `null`.
          example: true
        required: false
        description: Pass `true` to compute `page.total` (the matching record count). By default no count query runs and `page.total` is `null`.
        name: include_total
        in: query
      - schema:
          type: string
          description: ISO 4217 currency code for monetary field conversion. Defaults to USD.
          example: EUR
        required: false
        description: ISO 4217 currency code for monetary field conversion. Defaults to USD.
        name: currency
        in: query
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: List of notes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotesListResponse'
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: The request was malformed or failed validation.
                  details: null
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
        '401':
          description: Authentication required. The `Authorization` header was missing, the bearer token was malformed, or the token failed signature / expiry validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Authentication required — provide a valid bearer token.
                  details: null
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
        '402':
          description: '`CREDITS_EXHAUSTED` — the caller''s team has no credits left, or none granted yet. Only API-key and MCP requests are capped.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
        '403':
          description: Authentication succeeded but the caller's token does not include the permission required for this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                  details: null
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
        '429':
          description: Rate limit exceeded.
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '1'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Rate limit exceeded — retry after the delay in the `Retry-After` header.
                  details: null
        '503':
          description: '`SERVICE_UNAVAILABLE` — the caller''s team credits could not be checked. Retry shortly.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: SERVICE_UNAVAILABLE
                  message: The service is temporarily unavailable.
                  details: null
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
  /data/notes/{id}:
    get:
      operationId: getNote
      security:
      - oauth2:
        - read:news
      - bearerAuth:
        - read:news
      tags:
      - Notes
      summary: Get single note
      description: Returns one note by numeric ID or slug, including its body excerpt, publish date, type, monetary amount (for deal notes, converted to the requested `?currency=`), and any linked Dealroom entities.
      parameters:
      - schema:
          type: string
          minLength: 1
          example: '8765432'
          description: Numeric Dealroom note ID or slug.
        required: true
        description: Numeric Dealroom note ID or slug.
        name: id
        in: path
      - schema:
          type: string
          description: ISO 4217 currency code for monetary field conversion. Defaults to USD.
          example: EUR
        required: false
        description: ISO 4217 currency code for monetary field conversion. Defaults to USD.
        name: currency
        in: query
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Single note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoteDetailResponse'
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
        '401':
          description: Authentication required. The `Authorization` header was missing, the bearer token was malformed, or the token failed signature / expiry validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Authentication required — provide a valid bearer token.
                  details: null
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
        '402':
          description: '`CREDITS_EXHAUSTED` — the caller''s team has no credits left, or none granted yet. Only API-key and MCP requests are capped.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
        '403':
          description: Authentication succeeded but the caller's token does not include the permission required for this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: FORBIDDEN
                  message: You do not have permission to perform this action.
                  details: null
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: The requested resource was not found.
                  details: null
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
        '429':
          description: Rate limit exceeded.
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '1'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Rate limit exceeded — retry after the delay in the `Retry-After` header.
                  details: null
        '503':
          description: '`SERVICE_UNAVAILABLE` — the caller''s team credits could not be checked. Retry shortly.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: SERVICE_UNAVAILABLE
                  message: The service is temporarily unavailable.
                  details: null
          headers:
            X-Credits-Used:
              $ref: '#/components/headers/X-Credits-Used'
components:
  headers:
    Sunset:
      description: 'Present when the request pinned a superseded version: the date the version stops working and requests begin returning `400` (`YYYY-MM-DD`).'
      schema:
        type: string
        format: date
    Deprecation:
      description: 'Present when the request pinned a superseded version: the date that version was deprecated (`YYYY-MM-DD`).'
      schema:
        type: string
        format: date
    X-Credits-Used:
      description: Credits this request consumed, under the current credit schedule. Present on every response to an API-key request under `/data`, `/analytics` and `/reference`; `0` on an error response or a free endpoint. Absent when the request was not authenticated with an API key (so never on a `401`), or on unmetered endpoints. During open beta credits are drawn from the team's balance but not billed.
      schema:
        type: integer
        minimum: 0
      example: 25
  schemas:
    CappedPaginationPage:
      type: object
      properties:
        total:
          type:
          - number
          - 'null'
        limit:
          type: number
        offset:
          type: number
        next_cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page. Null when no further pages exist.
        prev_cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor for the previous page. Null when on the first page.
        capped:
          type: boolean
          description: True when the requested page size was reduced to the per-tier/ecosystem row cap.
        tier:
          $ref: '#/components/schemas/AccessTier'
        ecosystem:
          type:
          - string
          - 'null'
          description: Slug of the active ecosystem subdomain, or null when none is in scope.
      required:
      - total
      - limit
      - offset
      - next_cursor
      - prev_cursor
      - capped
      - tier
      - ecosystem
    OrganizationSubtype:
      type: string
      enum:
      - company
      - university
      - gov_ngo
      - investor
      description: 'The kind of organization: company, university, gov_ngo or investor.'
    Note:
      type: object
      properties:
        id:
          type: number
          description: Stable Dealroom note ID.
          example: 9876543
        url:
          type:
          - string
          - 'null'
          description: Canonical URL of the note on its publisher's site. Null for in-house editorial notes, which have no external source.
          example: https://techcrunch.com/2024/06/15/example-startup-raises-50m
        slug:
          type: string
          description: URL-safe note slug, unique per note; canonical routing key for /notes/:slug.
          example: example-startup-raises-50m-series-b-2024
        title:
          type:
          - string
          - 'null'
          description: Note headline.
          example: Example Startup raises $50M Series B led by Sequoia
        summary:
          type:
          - string
          - 'null'
          description: Short note summary (1-2 sentences).
          example: Example Startup announced a $50M Series B round…
        preview:
          type:
          - string
          - 'null'
          description: Short preview/teaser text distinct from `summary`.
          example: Example Startup announced…
        image_url:
          type:
          - string
          - 'null'
          description: Hero image URL for the note, if available.
          example: https://images.example.com/notes/note-9876543.jpg
        image_source:
          type:
          - string
          - 'null'
          description: Attribution/source of the hero image, if available.
          example: Unsplash
        source:
          type: string
          description: Publisher / source identifier. Always `dealroom` — every note is in-house.
          example: dealroom
        article_type:
          type:
          - string
          - 'null'
          description: 'Note type. Common values: `vc_round`, `ipo`, `acquisition`, `insight`, `event`, `partnership`.'
          example: vc_round
        category:
          type:
          - string
          - 'null'
          description: 'Display category: the `article_type` label, else the first industry of the entity the note is about, else `sector`. Null when none applies.'
          example: Funding rounds
        news_types:
          type: array
          items:
            type: object
            properties:
              id:
                type: number
                description: BigQuery-side news-type id.
                example: 3
              name:
                type:
                - string
                - 'null'
                description: News-type label, denormalised from BigQuery. Null when the source struct carried no name.
                example: Funding rounds
            required:
            - id
            - name
          description: Full list of BigQuery news-type tags for this note. `article_type` is a single whitelisted value derived from this array for backward compatibility; this is the complete, uncrushed list.
          example:
          - id: 3
            name: Funding rounds
          - id: 9
            name: Fintech
        is_news:
          type: boolean
          description: Whether this note is editorially selected as a news article. The `/data/news` lens filters on this flag; `/data/notes` does not.
          example: true
        type:
          type: string
          description: Note type classification. `public` today; the pitch types are reserved.
          example: public
        status:
          type: string
          description: Note publication status. `published`, or `expired` for a few legacy news notes.
          example: published
        published_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the note was published (RFC 3339).
          example: '2024-06-15T09:30:00.000Z'
        amount:
          type:
          - number
          - 'null'
          description: Deal amount in the active currency, for `vc_round`/`acquisition` notes, as a whole-unit integer.
          example: 50000000
        round_type:
          type:
          - string
          - 'null'
          description: Round type for VC-round notes (matches Transactions).
          example: SERIES_B
        deal_date:
          type:
          - string
          - 'null'
          format: date
          description: Day the deal closed (may differ from `published_at`).
          example: '2024-06-14'
        sector:
          type:
          - string
          - 'null'
          description: Sector classification, when known.
          example: Fintech
        hq_country:
          type:
          - string
          - 'null'
          description: HQ country of the primary mentioned company.
          example: United States
        enriched_summary:
          type:
          - string
          - 'null'
          description: 'Reserved: always null. `notes` has no enriched_summary column (the legacy column was always null in production too).'
          example: null
        importance_score:
          type:
          - number
          - 'null'
          description: Editorial ranking score — higher is more prominent. Null when unscored.
          example: 87.5
        is_pinned:
          type: boolean
          description: Whether this is the single most prominent (pinned) story. At most one note is pinned at a time.
          example: false
        source_urls:
          type: array
          items:
            type: string
          description: Full list of external source links, when known.
          example:
          - https://techcrunch.com/2024/06/15/example-startup-raises-50m
        references:
          type: array
          items:
            type: string
          description: Additional reference URLs cited by the note.
          example: []
        video_urls:
          type: array
          items:
            type: string
          description: Embedded/linked video URLs, when available.
          example: []
        pitch_deck_urls:
          type: array
          items:
            type: string
          description: Linked pitch deck URLs, when available.
          example: []
        author_entity_id:
          type:
          - number
          - 'null'
          description: Numeric ID of the authoring entity, when known.
          example: null
        author_kind:
          type:
          - string
          - 'null'
          description: Author classification (e.g. `editorial`, `contributor`), when known.
          example: null
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO 8601 timestamp the note itself was created (source system).
          example: '2024-06-15T10:30:00.000Z'
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: ISO 8601 timestamp the note was last updated (source system).
          example: '2024-06-15T10:30:00.000Z'
        entities:
          type: array
          items:
            type: object
            properties:
              mention_role:
                type:
                - string
                - 'null'
                description: How the entity features in the note — e.g. `subject` for the company a story is about, `investor` for a participant in its round.
                example: subject
              is_primary:
                type:
                - boolean
                - 'null'
                description: True for the single entity the note is principally about.
                example: true
              entity:
                $ref: '#/components/schemas/EntityRef'
            required:
            - mention_role
            - is_primary
            - entity
          description: Dealroom entities (companies, investors) referenced in the note, the primary one first, each as its reference.
      required:
      - id
      - url
      - slug
      - title
      - summary
      - preview
      - image_url
      - image_source
      - source
      - article_type
      - category
      - news_types
      - is_news
      - type
      - status
      - published_at
      - amount
      - round_type
      - deal_date
      - sector
      - hq_country
      - enriched_summary
      - importance_score
      - is_pinned
      - source_urls
      - references
      - video_urls
      - pitch_deck_urls
      - author_entity_id
      - author_kind
      - created_at
      - updated_at
      - entities
    AccessTier:
      type: string
      enum:
      - anonymous
      - free
      - premium
      description: 'The access tier applied to this request (anonymous, free, premium). API-key callers report premium: they receive the full field set and are not page-capped.'
    EntityType:
      type: string
      enum:
      - organization
      - person
      description: 'Top-level entity type: `organization` or `person`.'
    EntityRef:
      type: object
      properties:
        uuid:
          type: string
          description: Stable UUID of the entity.
        type:
          $ref: '#/components/schemas/EntityType'
        subtype:
          anyOf:
          - $ref: '#/components/schemas/OrganizationSubtype'
          - type: 'null'
          description: Organization subtype; always null for a person.
        name:
          type: string
          description: Display name.
        image:
          type:
          - string
          - 'null'
          description: Absolute image URL; null when none.
        dealroom_url:
          type:
          - string
          - 'null'
          description: Canonical profile URL on app.dealroom.co.
      required:
      - uuid
      - type
      - subtype
      - name
      - image
      - dealroom_url
      description: 'The identity of an entity embedded in another entity''s response. Closed: richer detail lives on the sub-resource, where tier redaction can reach it.'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - VALIDATION_ERROR
              - NOT_FOUND
              - UNAUTHORIZED
              - DATABASE_ERROR
              - UNKNOWN_FILTER
              - FILTER_VALIDATION_ERROR
              - UNSUPPORTED_OPERATOR
              - FILTER_PARSE_ERROR
              - QUERY_TIMEOUT
              - INTERNAL_SERVER_ERROR
              - INVALID_ENTITY_ID
              - PAGINATION_DEPTH_EXCEEDED
              - SCHEMA_ERROR
              - FORBIDDEN
              - EXTERNAL_SERVICE_ERROR
              - ACCOUNT_REQUIRED
              - INSTANCE_ACCESS_REQUIRED
              - SERVICE_UNAVAILABLE
              - RATE_LIMITED
              - CREDITS_EXHAUSTED
              - LIST_LOCKED
              - PATH_RENAMED
              - ENDPOINT_REMOVED
              description: Stable machine-readable error code.
            message:
              type: string
            details:
              anyOf:
              - type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                    message:
                      type: string
                  required:
                  - path
                  - message
              - type: object
                additionalProperties:
                  anyOf:
                  - type: string
                  - type: number
                  - type: boolean
              - type: 'null'
          required:
          - code
          - message
          - details
      required:
      - error
    NoteDetailResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Note'
        currency:
          type: string
      required:
      - data
      - currency
    NotesListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Note'
        page:
          $ref: '#/components/schemas/CappedPaginationPage'
        currency:
          type: string
      required:
      - data
      - page
      - currency
  parameters:
    ApiVersion:
      name: API-Version
      in: header
      required: false
      schema:
        type: string
        format: date
        example: '2026-10-09'
      description: Pin a Stripe-style date-based API version (`YYYY-MM-DD`). Omit to use the latest version (`2026-10-09`). A pinned version is supported for 30 days after it is superseded, after which it returns `400`.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Auth0 JWT access token. Paste a token obtained from your preferred OAuth2 flow. For machine-to-machine use, the OAuth2 client_credentials scheme below can mint a token directly from your `client_id` / `client_secret` inside the Swagger UI Authorize dialog.
    oauth2:
      type: oauth2
      description: OAuth2 client-credentials flow against the Dealroom Auth0 tenant. Use the `client_id` / `client_secret` from a Programmatic API key. Tokens are valid for 24h — Swagger UI will reuse the same token across operations. Revoking or deactivating a key rejects it on the next request (within a ≤5-minute server-side cache window), not at token expiry.
      flows:
        clientCredentials:
          tokenUrl: https://accounts.dealroom.co/oauth/token
          scopes:
            read:entities: Grant the read:entities permission
            read:transactions: Grant the read:transactions permission
            read:valuations: Grant the read:valuations permission
            read:investors: Grant the read:investors permission
            read:founders: Grant the read:founders permission
            read:dimensions: Grant the read:dimensions permission
            read:timeseries: Grant the read:timeseries permission
            read:aggregate: Grant the read:aggregate permission
            read:news: Grant the read:news permission
            read:jobs: Grant the read:jobs permission
            read:people: Grant the read:people permission
            read:search: Grant the read:search permission
x-tagGroups:
- name: Data
  tags:
  - Entities
  - Companies
  - Universities
  - Government & NGO
  - Transactions
  - Valuations
  - Investors
  - Funds
  - People
  - Founders
  - News
  - Jobs
  - Search
- name: Analytics
  tags:
  - Aggregate
  - Timeseries
- name: Reference
  tags:
  - Discovery
  - Filters
x-public-contract: true