API reference

See also

Looking for ways to interact with our source code archive from your applications or research projects? Learn how to use Software Heritage from your applications.

Here is the reference documentation of Software Heritage own software stack by components:

• swh.alter
  • Using swh-alter
    • Dependencies
    • Configuration
    • Removing objects from the archive
    • Resuming a removal from a recovery bundle
    • Restoring from a recovery bundle
    • Getting information from a recovery bundle
    • Extracting content stored in a recovery bundle
    • Operating recovery bundles remotely
    • Shared secrets rollover
    • For mirrors: watching and acting on removal notifications
  • Removal algorithm
    • Listing objects to be removed
    • Example of removing an origin
  • Recovery bundles
    • Description
    • Manifests
    • Objects
    • Encryption
    • Example
    • Implementation notes
    • Version history
  • swh.alter package
    • swh.alter.bech32 module
    • swh.alter.cli module
    • swh.alter.inventory module
    • swh.alter.mirror_notification_watcher module
    • swh.alter.notifications module
    • swh.alter.operations module
    • swh.alter.progressbar module
    • swh.alter.recovery_bundle module
    • swh.alter.removable module
    • swh.alter.subgraph module
    • swh.alter.utils module
• swh.auth
  • Reference Documentation
    • Command-line interface
    • Django components
    • swh.auth package
• swh.coarnotify
  • Explanations
    • Explanations
    • swh.coarnotify package
  • How to guides
    • How-to guides
  • References
    • References
• swh.core
  • Reference Documentation
    • Command-line interface
    • Common database utilities
    • swh.core package
• swh.counters
  • swh.counters package
    • swh.counters.api package
    • swh.counters.cli module
    • swh.counters.history module
    • swh.counters.in_memory module
    • swh.counters.interface module
    • swh.counters.journal_client module
    • swh.counters.kafka_client module
    • swh.counters.redis module
    • get_counters()
    • get_history()
• swh.dataportal
  • How to guides
    • How to guides
  • References
    • References
• swh.datasets
  • Luigi workflows
    • Statistics
    • Graph export
    • Compressed graph
    • Blobs datasets
    • File names
    • Provenance
    • Origin contributors
    • Topology
  • Command-line interface
    • swh datasets
  • swh.datasets package
    • swh.datasets.luigi package
    • swh.datasets.cli module
    • swh.datasets.download module
    • swh.datasets.shell module
• swh.deposit
  • Description
    • Deposit API
    • Deposit internals
    • Specifications
    • swh.deposit package
  • Reference Documentation
    • Command-line interface
• swh.digestmap
  • Direct use
  • Use as a Software Heritage storage backend
  • Publicly-available digestmaps
  • Develop
• swh.export
  • Software Heritage Graph Dataset
    • Dataset
    • Relational schema
    • Setup on Amazon Athena
    • Setup on Azure Databricks
    • Indices and tables
  • Exporting a dataset
    • Graph dataset
  • Exporting a subdataset
    • Step 1. Obtain the list of origins
    • Step 2. Build the list of SWHIDs
    • Step 3. Generate the subdataset on Athena
    • Step 4. Upload and document the newly generated subdataset
  • swh.export package
    • swh.export.exporters package
    • swh.export.test namespace
    • swh.export.athena module
    • swh.export.cli module
    • swh.export.exporter module
    • swh.export.fullnames module
    • swh.export.journalprocessor module
    • swh.export.luigi module
    • swh.export.relational module
    • swh.export.utils module
• swh.fuse
  • Demo
  • Bibliography
    • Tutorial
    • Configuration
    • Advice for parallelization
    • Design notes
    • Command-line interface
    • swh.fuse package
• swh.graph
  • Bibliography
    • Quickstart
    • Graph Querying HTTP API
    • Using the gRPC API
    • Rust API
    • Design tips for Rust code using swh-graph
    • Memory & Performance tuning
    • Graph compression
    • Command-line interface
    • Docker environment
    • git2graph
    • Test graphs
    • Example dataset
    • Provenance index
    • swh-graph glossary
    • swh.graph namespace
• swh.graph.libs
  • swh.graph.libs package
    • swh.graph.libs.luigi package
    • swh.graph.libs.shell module
• Software Heritage GraphQL API
  • Running locally
  • Running a query
  • Using curl
  • Using Python requests
  • Pagination
    • Example for pagination using edges
    • Example for pagination using nodes
• Design
  • Architecture
  • Schema
  • Resolvers
  • Resolver factory
  • Custom Scalars
  • Targets and union types
  • Errors
    • Client errors not reported in Sentry are
    • Other possible errors (reported in Sentry)
  • Backends
  • Middlewares
  • Local paginations
  • Tests
  • Add a new Scalar field inside a type
  • Add a new type field inside another type
  • Add a new entrypoint
  • Cost calculator
  • Client
  • Future works
    • swh.graphql package
• swh.indexer
  • Software Heritage - Indexer
  • Metadata workflow
    • Intrinsic metadata
    • Extrinsic metadata
    • Implementation status
    • Tutorials
    • Adding support for additional ecosystem-specific intrinsic metadata
    • Adding support for additional ecosystem-specific extrinsic metadata
  • Custom indexers and metadata mappings
    • Indexers
    • Metadata mappings
  • SwhPkg Vocabulary
    • SwhPkg Terms
  • swh.indexer package
    • swh.indexer.citation package
    • swh.indexer.metadata_mapping package
    • swh.indexer.storage package
    • swh.indexer.cli module
    • swh.indexer.codemeta module
    • swh.indexer.fossology_license module
    • swh.indexer.indexer module
    • swh.indexer.metadata module
    • swh.indexer.metadata_detector module
    • swh.indexer.mimetype module
    • swh.indexer.namespaces module
    • swh.indexer.origin_head module
    • swh.indexer.rehash module
    • get_datastore()
    • get_indexer_names()
    • get_indexer()
    • load_indexers()
  • Reference Documentation
    • Command-line interface
• swh.journal
  • Software Heritage Journal clients
    • Parallelization
    • Authentication
    • Order guarantees and replaying
  • swh.journal package
    • swh.journal.writer package
    • swh.journal.client module
    • swh.journal.pytest_plugin module
    • swh.journal.serializers module
• swh.lister
  • Dependencies
  • Local deployment
    • Lister configuration
    • Configuration file sample
  • Executing a lister
  • Licensing
  • Overview
    • Tutorial: list the content of your favorite forge in just a few steps
    • Tutorial: run a lister within docker-dev in just a few steps
    • Save a forge
    • swh.lister package
  • Reference Documentation
    • Command-line interface
• swh.loader
  • swh.loader.core
    • Package loaders
    • VCS loaders
    • Reference Documentation
  • swh.loader.bzr
    • Software Heritage - How Bazaar/Breezy works
    • swh.loader.bzr package
  • Software Heritage - CVS loader
    • Features
    • Known Limitations
    • Acknowledgements
    • Licensing information
  • Running Tests
  • CLI run
    • Reference Documentation
  • swh.loader.git
    • License
    • Dependencies
    • Requirements
    • CLI Run
    • Reference Documentation
  • swh.loader.mercurial
    • CLI run
    • Reference Documentation
  • swh.loader.metadata
    • swh.loader.metadata package
  • swh.loader.svn
    • CLI run
    • Reference Documentation
• swh.model
  • Data model
    • Source code hosting places
    • Software artifacts
    • Data structure
    • Extended data model
  • SoftWare Heritage persistent IDentifiers (SWHIDs)
    • Overview
    • Syntax
    • Semantics
    • Interoperability
    • Examples
    • Implementation
    • References
  • Command-line interface
    • swh identify
  • swh.model package
    • swh.model.fields package
    • swh.model.cli module
    • swh.model.collections module
    • swh.model.discovery module
    • swh.model.exceptions module
    • swh.model.from_disk module
    • swh.model.git_objects module
    • swh.model.hashutil module
    • swh.model.hypothesis_strategies module
    • swh.model.merkle module
    • swh.model.model module
    • swh.model.swhids module
    • swh.model.toposort module
    • swh.model.validators module
• swh.objstorage
  • Quick start
  • Test dependencies
  • Reference Documentation
    • Command-line interface
    • Winery backend
    • swh.objstorage namespace
• swh.objstorage.replayer
  • Quick start
  • Reference Documentation
    • Command-line interface
    • swh.objstorage.replayer package
• Software Heritage - Provenance
• Description
  • Using the gRPC API
    • Quickstart
  • swh-provenance design
    • Database format and layout
    • Database construction
    • Queries
  • swh.provenance package
    • swh.provenance.api namespace
    • swh.provenance.backend namespace
    • swh.provenance.grpc namespace
    • swh.provenance.cli module
    • swh.provenance.exc module
    • swh.provenance.grpc_client module
    • swh.provenance.grpc_server module
    • swh.provenance.interface module
    • swh.provenance.luigi module
    • swh.provenance.pytest_plugin module
    • swh.provenance.shell module
    • get_provenance()
• swh.scanner
  • Getting Started
    • Installation
    • Registering to the Software Heritage Archive
    • Configuring your scan
    • Running a Scan
    • Further Configuration
• swh.scheduler
  • Description
    • Generic task scheduler
    • Origin visits scheduler
  • Generic SWH Task Model
  • Writing a new worker for a new swh-task-type
  • Reference Documentation
    • Command-line interface
    • Software Heritage Scheduler Simulator
    • swh.scheduler package
• swh.scrubber
  • Checking
    • Storage
    • Object storage
    • Journal
  • Recovery
  • Reinjection
    • Command-line interface
    • swh.scrubber package
• swh.search
  • Dependencies
  • Make targets
    • Command-line interface
    • Search Query Language
    • swh.search package
  • Reference Documentation
• swh.shard
  • Quick Start
    • Command Line Tool
  • Reference Documentation
    • Read Shard format
    • Benchmarks
    • swh.shard package
• swh.storage
  • Quick start
    • Dependencies
    • Installation
  • Tests
    • tox
  • Development
    • Sample configuration
    • Starting the storage server
    • And then what?
  • Cassandra
  • Using swh-storage
  • Archive copies
  • Specifications
    • Extrinsic metadata specification
    • Object Masking
    • swh.storage package
  • Reference Documentation
    • Database schema
    • Cassandra migrations
    • Storage replayer
    • Command-line interface
• swh.vault
  • Architecture
    • The Vault backend
    • The cookers
  • Reference Documentation
    • Command-line interface
• swh.web
  • Technical details
  • How to build, run and test
    • Backend requirements
    • Frontend requirements
    • Make targets to execute the applications
    • Make targets to test the applications
    • Yarn targets
• swh.web.client
  • Sample usage
  • Authentication
• swh.webhooks
  • API Overview
    • Event type
    • Endpoint
    • Event