diff --git a/docs/api/get-v1-importfindings.md b/docs/api/get-v1-importfindings.md new file mode 100644 index 00000000000..b925e79ed1f --- /dev/null +++ b/docs/api/get-v1-importfindings.md @@ -0,0 +1,59 @@ +--- +layout: page +title: GET /v1experimental/importfindings +permalink: /get-v1-importfindings/ +parent: API +nav_order: 5 +--- +# GET /v1experimental/importfindings/{source} +Experimental +{: .label } + +Given a specific OSV.dev source, report any records that are failing import-time quality checks. + +{: .no_toc } + +
+ + Table of contents + + {: .text-delta } +- TOC +{:toc} +
+ +## Experimental endpoint + +This API endpoint is still considered experimental. It is targeted to operators +of home databases that OSV.dev imports from. We would value any and all +feedback. If you give this a try, please consider [opening an +issue](https://github.com/google/osv.dev/issues/new) and letting us know about +any pain points or highlights. + +## Purpose + +The purpose of this endpoint is give OSV record providers (home database +operators) a machine-readable way to reason about records they have published that +do not meet [OSV.dev's quality bar](data_quality.html) (and therefore have not been imported). + +## Parameters + +The only parameter you need for this API call is the source, in order to construct the URL. + +`https://api.osv.dev/v1/importfindings/{source}` + +The `source` value is the same as the `name` value in [`source.yaml`](https://github.com/google/osv.dev/blob/master/source.yaml) + +Case Sensitivity: API requests are case-sensitive. Please ensure that you use the correct case for parameter names and values. For example, use 'ghsa' instead of 'GHSA'. + +## Request sample + +```bash +curl "https://api.osv.dev/v1experimental/importfindings/example" +``` + +## Example 200 response + +``` +{"invalid_records":[{"bug_id":"EX-1234","source":"example","findings":["IMPORT_FINDING_TYPE_INVALID_JSON"],"first_seen":"2024-12-19T15:18:00.945105Z","last_attempt":"2024-12-19T15:18:00.945105Z"}]} +``` diff --git a/docs/api/index.md b/docs/api/index.md index e19f2f52407..8b5970f1553 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -8,21 +8,25 @@ nav_order: 2 # API (1.0) ## Download the OpenAPI specification + [Download Here](https://osv.dev/docs/osv_service_v1.swagger.json){: .btn .btn-purple} ## OSV API ### Want a quick example? -Please see the [quickstart](api-quickstart.md). + +Please see the [quickstart](api-quickstart.md). ### How does the API work? -There are four different types of requests that can be made of the API. +There are five different types of requests that can be made of the API. 1. Query vulnerabilities for a particular project at a given [commit hash or version](post-v1-query.md). 2. [Batched query vulnerabilities](post-v1-querybatch.md) for given package versions and commit hashes. 3. Return a `Vulnerability` object for a given [OSV ID](get-v1-vulns.md). 4. Return a list of [probable versions](post-v1-determineversion.md) of a specified C/C++ project. (**Experimental**) +5. Retrieve [records failing import-time quality checks](get-v1-importfindings.md), by record source (**Experimental**) ### Is the API rate limited? -Currently there are no limits on the API. \ No newline at end of file + +Currently there are no limits on the API.