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