Make a multi-step code & metadata deposit#

API/CLI reference

This page will help you make a deposit without getting into too much details, the API reference and the CLI reference are available to explain all the technical specifications.

Partial deposits

This method of depositing artefacts to the archive is a bit more complicated than the other one, if your artefacts are not larger than 100Mo we would recommend sticking to the simpler (one shot) method.

If you have multiple code artefacts or if you need to make your deposit in two or more times, you can make use of the partial deposit functionality.

Checklist#

You have access to your account credentials
You have a software artefact at hand and its associated metadata (if not you need to prepare your artefacts and metadata.)
This is the first time you’re depositing for this origin (if you already made deposits for this origin you want to make a new deposit for an existing origin)
You have either the CLI installed or a tool to make API calls, we will use curl here, but commands could be easily adapted to another application

Make the deposit in multiple steps#

Deposit instance URL

In the examples below the staging deposit url https://deposit.staging.swh.network is used to avoid experimenting on the production instance of the deposit server. Make sure you switch to https://deposit.softwareheritage.org when you are ready.

In the example below we will make a first deposit with a code artefact then a second one and finally a third one with the metadata.

First partial deposit#

API

Note the In-Progress: true header. Also make sure the mimetype matches your file, here SOFTWARE_ARTEFACT1 is a zip archive.

curl -i -u USERNAME:PASSWORD \
     -F "file=@SOFTWARE_ARTEFACT1;type=application/zip;filename=payload" \
     -H 'In-Progress: true' \
     -XPOST https://deposit.staging.swh.network/1/COLLECTION/

CLI

Note the ‘–partial’ flag ‘–archive’ argument, as we’re sending a new software artefact.

swh deposit upload \
  --username USERNAME --password PASSWORD \
  --url https://deposit.staging.swh.network/1 \
  --archive SOFTWARE_ARTEFACT1 \
  --partial \
  --format json

Will return the following response (note the partial status and the deposit_id value):

API

<entry xmlns="http://www.w3.org/2005/Atom"
      xmlns:sword="http://purl.org/net/sword/"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
      >
    <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
    <swhdeposit:deposit_date>Jan. 1, 2025, 09:00 a.m.</swhdeposit:deposit_date>
    <swhdeposit:deposit_archive>None</swhdeposit:deposit_archive>
    <swhdeposit:deposit_status>partial</swhdeposit:deposit_status>

    <!-- Edit-IRI -->
    <link rel="edit" href="/1/COLLECTION/DEPOSIT_ID/metadata/" />
    <!-- EM-IRI -->
    <link rel="edit-media" href="/1/COLLECTION/DEPOSIT_ID/media/"/>
    <!-- SE-IRI -->
    <link rel="http://purl.org/net/sword/terms/add" href="/1/COLLECTION/DEPOSIT_ID/metadata/" />
    <!-- State-IRI -->
    <link rel="alternate" href="/1/COLLECTION/DEPOSIT_ID/status/"/>

    <sword:packaging>http://purl.org/net/sword/package/SimpleZip</sword:packaging>
</entry>

CLI

{
  "deposit_status": "partial",
  "deposit_id": "DEPOSIT_ID",
  "deposit_date": "Jan. 1, 2025, 09:00 a.m.",
  "deposit_status_detail": null
}

Second partial deposit#

Instead of creating a new deposit we’ll update the previous one referenced by DEPOSIT_ID. In our example, we’re making this deposit in three steps, so we will indicate in our calls that this deposit is still partial. The number of steps does not matter, the only important thing is to make all calls partial except the last one.

API

Note the In-Progress: true header, the DEPOSIT_ID in the URL and the /media/ endpoint as we’re sending a new software artefact. Also make sure the mimetype matches your file, here SOFTWARE_ARTEFACT2 is a tarball.

curl -i -u USERNAME:PASSWORD \
     -F "file=@SOFTWARE_ARTEFACT2;type=application/x-tar;filename=payload" \
     -H 'In-Progress: true' \
     -XPOST https://deposit.staging.swh.network/1/COLLECTION/DEPOSIT_ID/media/

CLI

Note the ‘–partial’ flag, the –deposit-id argument and the ‘–archive’ argument, as we’re sending a new software artefact.

swh deposit upload \
  --username USERNAME --password PASSWORD \
  --url https://deposit.staging.swh.network/1 \
  --archive SOFTWARE_ARTEFACT2 \
  --deposit-id DEPOSIT_ID \
  --partial \
  --format json

This will return a response similar to the previous one.

Third (and last) partial deposit#

This deposit will only consist of the metadata. To indicate this is the last step we will send include “not partial anymore” parameter in our call.

API

Note the In-Progress: false header, the DEPOSIT_ID in the URL and the /metadata/ as we’re pushing only metadata.

curl -i -u USERNAME:PASSWORD \
     -F "atom=@METADATA_FILE;type=application/atom+xml;charset=UTF-8" \
     -H 'In-Progress: false' \
     -XPOST https://deposit.staging.swh.network/1/COLLECTION/DEPOSIT_ID/metadata/

CLI

Note the ‘–not-partial’ flag, the –deposit-id argument and the ‘–metadata’ argument, as we’re pushing only metadata.

swh deposit upload \
  --username USERNAME --password PASSWORD \
  --url https://deposit.staging.swh.network/1 \
  --metadata METADATA_FILE \
  --deposit-id DEPOSIT_ID \
  --not-partial \
  --format json

Check a deposit status#

Your deposit will go through multiple steps before appearing in the archive, you can check the status of your deposit and get its SWHID:

API

curl -i -u USERNAME:PASSWORD \
     -XGET https://deposit.staging.swh.network/1/COLLECTION/DEPOSIT_ID/status/

CLI

swh deposit status \
  --username USERNAME --password PASSWORD \
  --url https://deposit.staging.swh.network/1 \
  --deposit-id DEPOSIT_ID \
  --format json

Will return the following response:

API

<entry xmlns="http://www.w3.org/2005/Atom"
      xmlns:sword="http://purl.org/net/sword/"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
      >
    <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
    <swhdeposit:deposit_status>done</swhdeposit:deposit_status>
    <swhdeposit:deposit_status_detail>The deposit has been successfully loaded into the Software Heritage archive</swhdeposit:deposit_status_detail>
    <swhdeposit:deposit_swh_id>SWHID</swhdeposit:deposit_swh_id>
    <swhdeposit:deposit_swh_id_context>SWHID_CONTEXT</swhdeposit:deposit_swh_id>
</entry>

CLI

{
  "deposit_id": "DEPOSIT_ID",
  "deposit_status": "done",
  "deposit_swh_id": "SWHID",
  "deposit_swh_id_context": "SWHID_CONTEXT",
  "deposit_status_detail": "The deposit has been successfully loaded into the Software Heritage archive"
}

A deposited status means the deposit is complete but still needs to be checked to ensure data consistency. You can check your deposit status to follow the process.

Repeat the same calls until the status changes:

API

<entry xmlns="http://www.w3.org/2005/Atom"
      xmlns:sword="http://purl.org/net/sword/"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:swhdeposit="https://www.softwareheritage.org/schema/2018/deposit"
      >
    <swhdeposit:deposit_id>DEPOSIT_ID</swhdeposit:deposit_id>
    <swhdeposit:deposit_status>done</swhdeposit:deposit_status>
    <swhdeposit:deposit_status_detail>The deposit has been successfully loaded into the Software Heritage archive</swhdeposit:deposit_status_detail>
    <swhdeposit:deposit_swh_id>SWHID</swhdeposit:deposit_swh_id>
    <swhdeposit:deposit_swh_id_context>SWHID_CONTEXT</swhdeposit:deposit_swh_id>
</entry>

CLI

{
  "deposit_id": "DEPOSIT_ID",
  "deposit_status": "done",
  "deposit_swh_id": "SWHID",
  "deposit_swh_id_context": "SWHID_CONTEXT",
  "deposit_status_detail": "The deposit has been successfully loaded into the Software Heritage archive"
}

A done status means the deposit is now integrated in the archive, so you can access https://deposit.staging.swh.network/SWHID, https://deposit.staging.swh.network/SWHID_CONTEXT, or https://deposit.staging.swh.network/browse/origin/?origin_url=ORIGIN_URL to view the result of it.

What’s next ?#

Now that you’ve made your first deposit you might want to integrate it in your website or push another version of the software.