Getting started

The Vault is a service in charge of reconstructing parts of the archive as self-contained bundles, that can then be imported locally, for instance in a Git repository. This is basically where you can do a git clone of a repository stored in Software Heritage.

The Vault is asynchronous : you first need to do a request to prepare the bundle you need, and then a second request to fetch the bundle once the Vault has finished to reconstitute the bundle.

Example: retrieving a directory

First, ask the Vault to prepare your bundle:

curl -X POST https://archive.softwareheritage.org/api/1/vault/directory/:dir_id/

where :dir_id is a directory identifier. This initial request and all subsequent requests to this endpoint will return some JSON data containing information about the progress of bundle creation:

{
    "id": 42,
    "fetch_url": "/api/1/vault/directory/:dir_id/raw/",
    "obj_id": ":dir_id",
    "obj_type": "directory",
    "progress_message": "Creating tarball...",
    "status": "pending"
}

Once the status is done, you can fetch the bundle at the address given in the fetch_url field.

curl -o bundle.tar.gz https://archive.softwareheritage.org/api/1/vault/directory/:dir_id/raw
tar xaf bundle.tar.gz

E-mail notifications

You can also ask to be notified by e-mail once the bundle you requested is ready, by giving an email POST parameter:

curl -X POST -d 'email=example@example.com' \
    https://archive.softwareheritage.org/api/1/vault/directory/:dir_id/

API reference

For a more exhaustive overview of the Vault API, see the Vault API Reference.