Skip to content
forgit api docs

Create a snapshot of dependencies for a repository

POST
/repos/{owner}/{repo}/dependency-graph/snapshots

Create a new snapshot of a repository’s dependencies.

The authenticated user must have access to the repository.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

The account owner of the repository. The name is not case sensitive.

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
snapshot

Create a new snapshot of a repository’s dependencies.

object
version
required

The version of the repository snapshot submission.

integer
job
required
object
id
required

The external ID of the job.

string
correlator
required

Correlator provides a key that is used to group snapshots submitted over time. Only the “latest” submitted snapshot for a given combination of job.correlator and detector.name will be considered when calculating a repository’s current dependencies. Correlator should be as unique as it takes to distinguish all detection runs for a given “wave” of CI workflow you run. If you’re using GitHub Actions, a good default value for this could be the environment variables GITHUB_WORKFLOW and GITHUB_JOB concatenated together. If you’re using a build matrix, then you’ll also need to add additional key(s) to distinguish between each submission inside a matrix variation.

string
html_url

The url for the job.

string
sha
required

The commit SHA associated with this dependency snapshot. Maximum length: 40 characters.

string
>= 40 characters <= 40 characters
ref
required

The repository branch that triggered this snapshot.

string
/^refs//
detector
required

A description of the detector used.

object
name
required

The name of the detector used.

string
version
required

The version of the detector used.

string
url
required

The url of the detector used.

string
metadata
metadata

User-defined metadata to store domain-specific information limited to 8 keys with scalar values.

object
<= 8 properties
key
additional properties
Any of:
string
manifests

A collection of package manifests, which are a collection of related dependencies declared in a file or representing a logical group of dependencies.

object
key
additional properties
object
name
required

The name of the manifest.

string
file
object
source_location

The path of the manifest file relative to the root of the Git repository.

string
metadata
metadata

User-defined metadata to store domain-specific information limited to 8 keys with scalar values.

object
<= 8 properties
key
additional properties
Any of:
string
resolved

A collection of resolved package dependencies.

object
key
additional properties
object
package_url

Package-url (PURL) of dependency. See https://github.com/package-url/purl-spec for more details.

string
/^pkg/
metadata
metadata

User-defined metadata to store domain-specific information limited to 8 keys with scalar values.

object
<= 8 properties
key
additional properties
Any of:
string
relationship

A notation of whether a dependency is requested directly by this manifest or is a dependency of another dependency.

string
Allowed values: direct indirect
scope

A notation of whether the dependency is required for the primary build artifact (runtime) or is only used for development. Future versions of this specification may allow for more granular scopes.

string
Allowed values: runtime development
dependencies

Array of package-url (PURLs) of direct child dependencies.

Array<string>
scanned
required

The time at which the snapshot was scanned.

string format: date-time
Examples
Example example-of-a-dependency-submission 
{
  "version": 0,
  "sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "ref": "refs/heads/main",
  "job": {
    "correlator": "yourworkflowname_youractionname",
    "id": "yourrunid"
  },
  "detector": {
    "name": "octo-detector",
    "version": "0.0.1",
    "url": "https://github.com/octo-org/octo-repo"
  },
  "scanned": "2022-06-14T20:25:00Z",
  "manifests": {
    "package-lock.json": {
      "name": "package-lock.json",
      "file": {
        "source_location": "src/package-lock.json"
      },
      "resolved": {
        "@actions/core": {
          "package_url": "pkg:/npm/%40actions/core@1.1.9",
          "dependencies": [
            "@actions/http-client"
          ]
        },
        "@actions/http-client": {
          "package_url": "pkg:/npm/%40actions/http-client@1.0.7",
          "dependencies": [
            "tunnel"
          ]
        },
        "tunnel": {
          "package_url": "pkg:/npm/tunnel@0.0.6"
        }
      }
    }
  }
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
object
id
required

ID of the created snapshot.

integer
created_at
required

The time at which the snapshot was created.

string
result
required

Either “SUCCESS”, “ACCEPTED”, or “INVALID”. “SUCCESS” indicates that the snapshot was successfully created and the repository’s dependencies were updated. “ACCEPTED” indicates that the snapshot was successfully created, but the repository’s dependencies were not updated. “INVALID” indicates that the snapshot was malformed.

string
message
required

A message providing further details about the result, such as why the dependencies were not updated.

string
Examples
Example example-of-a-dependency-submission 
{
  "id": 12345,
  "created_at": "2018-05-04T01:14:52Z",
  "message": "Dependency results for the repo have been successfully updated.",
  "result": "SUCCESS"
}