openapi: 3.1.0
info:
  title: OSV (Open Source Vulnerabilities) API
  description: >-
    OSV is a distributed open source vulnerability database and triage
    infrastructure project hosted by the Open Source Security Foundation
    (OpenSSF). The OSV API exposes vulnerability records keyed to specific
    package versions or commits across multiple ecosystems (npm, PyPI,
    Maven, Go, NuGet, RubyGems, Cargo, Packagist, Hex, OSS-Fuzz, Linux,
    Android, GitHub Actions, etc.).
  version: '1'
  contact:
    name: OSV
    url: https://osv.dev/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: OSV API documentation
  url: https://google.github.io/osv.dev/api/
servers:
  - url: https://api.osv.dev
    description: OSV production API
paths:
  /v1/query:
    post:
      operationId: queryVulnerabilities
      summary: Query vulnerabilities for a package or commit
      description: >-
        Query vulnerabilities for a project at a given commit hash or for a
        specific package and version. Returns matching OSV vulnerability
        records.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Matching vulnerabilities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  vulns:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vulnerability'
  /v1/querybatch:
    post:
      operationId: queryVulnerabilitiesBatch
      summary: Batched vulnerability query
      description: >-
        Batched query for multiple package versions or commit hashes in a
        single request. Returns vulnerability ID lists per query that can be
        hydrated via /v1/vulns/{id}.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queries:
                  type: array
                  items:
                    $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Per-query vulnerability ID lists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        vulns:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              modified:
                                type: string
                                format: date-time
  /v1/vulns/{id}:
    get:
      operationId: getVulnerability
      summary: Get vulnerability by OSV ID
      description: Return a Vulnerability object for a given OSV ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: GHSA-xxxx-xxxx-xxxx
      responses:
        '200':
          description: Vulnerability record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vulnerability'
        '404':
          description: Vulnerability not found.
  /v1experimental/determineversion:
    post:
      operationId: determineVersion
      summary: Determine probable versions of a C/C++ project (experimental)
      description: >-
        Experimental endpoint that returns probable versions of a C/C++
        project given a set of file hashes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Candidate versions.
  /v1experimental/importfindings:
    get:
      operationId: importFindings
      summary: Import-time quality check findings (experimental)
      description: >-
        Retrieve records that failed import-time quality checks for a given
        source.
      parameters:
        - name: source
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Import findings.
components:
  schemas:
    QueryRequest:
      type: object
      properties:
        commit:
          type: string
          description: Commit hash to query.
        version:
          type: string
          description: Package version.
        package:
          type: object
          properties:
            name:
              type: string
            ecosystem:
              type: string
              description: e.g., npm, PyPI, Maven, Go, crates.io, RubyGems, NuGet, Packagist, Hex, GitHub Actions, Linux, Android, OSS-Fuzz.
            purl:
              type: string
              description: Package URL (purl).
        page_token:
          type: string
    Vulnerability:
      type: object
      description: OSV schema vulnerability record.
      properties:
        schema_version:
          type: string
        id:
          type: string
        modified:
          type: string
          format: date-time
        published:
          type: string
          format: date-time
        withdrawn:
          type: string
          format: date-time
        aliases:
          type: array
          items:
            type: string
        related:
          type: array
          items:
            type: string
        summary:
          type: string
        details:
          type: string
        severity:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              score:
                type: string
        affected:
          type: array
          items:
            type: object
            properties:
              package:
                type: object
                properties:
                  ecosystem:
                    type: string
                  name:
                    type: string
                  purl:
                    type: string
              ranges:
                type: array
                items:
                  type: object
              versions:
                type: array
                items:
                  type: string
              ecosystem_specific:
                type: object
              database_specific:
                type: object
        references:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              url:
                type: string
        credits:
          type: array
          items:
            type: object
        database_specific:
          type: object