You can jump directly to the endpoint index , which lists all available API functionalities, or read on for more general information about the API.
The Software Heritage project harvests publicly available source code by tracking software distribution channels such as version control systems, tarball releases, and distribution packages.
All retrieved source code and related metadata are stored in the Software Heritage archive, that is conceptually a Merkle DAG. All nodes in the graph are content-addressable, i.e., their node identifiers are computed by hashing their content and, transitively, that of all nodes reachable from them; and no node or edge is ever removed from the graph: the Software Heritage archive is an append-only data structure.
The following types of objects (i.e., graph nodes) can be found in the Software Heritage archive (for more information see the Software Heritage glossary):
The current version of the API is v1.
Warning: this version of the API is not to be considered stable yet. Non-backward compatible changes might happen even without changing the API version number.
API access is over HTTPS.
All API endpoints are rooted at https://archive.softwareheritage.org/api/1/.
Data is sent and received as JSON by default.
Example:
from the command line:
curl -i https://archive.softwareheritage.org/api/1/stat/counters/The response format can be overridden using the
Accept request header. In particular,
Accept: text/html (that web browsers send by default) requests HTML pretty-printing, whereas
Accept: application/yaml requests YAML-encoded responses.
Example:
from the command line:
curl -i -H 'Accept: application/yaml' https://archive.softwareheritage.org/api/1/stat/counters/Some API endpoints can be tweaked by passing optional parameters. For GET requests, optional parameters can be passed as an HTTP query string.
The optional parameter
fields is accepted by all endpoints that return dictionaries and can be used to restrict the list of fields returned
by the API, in case you are not interested in all of them. By default, all available fields are returned.
Example:
from the command line:
curl https://archive.softwareheritage.org/api/1/stat/counters/?fields=content,directory,revisionWhile API endpoints will return different kinds of errors depending on their own semantics, some error patterns are common across all endpoints.
Sending malformed data, including syntactically incorrect object identifiers, will result in a
400 Bad Request HTTP response. Example:
from the command line:
curl -i https://archive.softwareheritage.org/api/1/content/deadbeef/Requesting non existent resources will result in a
404 Not Found HTTP response. Example:
from the command line:
curl -i https://archive.softwareheritage.org/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/Unavailability of the underlying storage backend will result in a
503 Service Unavailable HTTP response.
While attempting to decode UTF-8 strings from raw bytes stored in the archive, some errors
+might happen when generating an API response. In that case, an extra field decoding_failures
+will be added to each concerned JSON object (possibly nested). It will contain the list of its key
+names where UTF-8 decoding failed.
+
+A string that could not be decoded will have the bytes of its invalid UTF-8 sequences escaped as
+\\x<hex value>.
+
Requests that might potentially return many items will be paginated.
Page size is set to a default (usually: 10 items), but might be overridden with the
per_page query parameter up to a maximum (usually: 50 items). Example:
curl https://archive.softwareheritage.org/api/1/origin/1/visits/?per_page=2To navigate through paginated results, a
Link HTTP response header is available to link the current result page to the next one. Example:
curl -i https://archive.softwareheritage.org/api/1/origin/1/visits/?per_page=2 | grep ^Link:
Link: </api/1/origin/1/visits/?last_visit=2&per_page=2>; rel="next",Due to limited resource availability on the back end side, API usage is currently rate limited. Furthermore, as API usage is currently entirely anonymous (i.e., without any authentication), API "users" are currently identified by their origin IP address.
Three HTTP response fields will inform you about the current state of limits that apply to your current rate limiting bucket:
X-RateLimit-Limit: maximum number of permitted requests per hourX-RateLimit-Remaining: number of permitted requests remaining before the next resetX-RateLimit-Reset: the time (expressed in
Unix time seconds) at which the current rate limiting will expire, resetting to a fresh
X-RateLimit-Limit
Example:
curl -i https://archive.softwareheritage.org/api/1/stat/counters/ | grep ^X-RateLimit
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1485794532