Accessing Collections, Deposits, Files, and Fixity Reports
The Vault API provides access to key metadata about your stored collections, deposits, individual files, and fixity reports. These APIs are useful for generating reports, integrating with external systems, auditing submissions, or reviewing content inventory.
Overview
All endpoints support secure, read-only access to your organization’s Vault content. For more detailed technical information, please refer to: https://vault.archive-it.org/api/v1/docs
In this article:
- Collections API
- Deposit Reports API
- Files API
- Fixity Report Summary API
- Fixity Report API
- Notes and Best Practices
Authentication is required. Self-service API key generation is now available to Admin-level users on the Administration page in your Vault account. For more detailed information, see Generating API Keys.
Collections API
Endpoint
GET /api/v1/collections
Description
List collections in your Vault account.
Returns a list of your organization’s collections, including names, IDs, and basic metadata. For more technical information, please refer to this API documentation.
Common Use Cases
- Identify the Collection ID of a specific collection.
- Utilize the Collection ID in conjunction with the Files API to generate a folder and item-level inventory for a particular collection.
- Retrieve a list of all collections in your Vault Account
- Generate a summary of content within a collection.
Response Schema
| Field | Description | Example |
|---|---|---|
| collection_id | Unique identifier for the collection | 325 |
| collection_name | Human-readable name of the collection | “Newspapers” |
| file_count | Number of files in the collection | 97 |
| size | Total size of collection contents in bytes | 1073741824 |
Deposit Reports API
Endpoint
GET /api/v1/reports/deposit
Description
List deposit report information.
Returns a list of deposits submitted to Vault. Each deposit includes metadata like the number of files, size, state, and replication status. For more technical information, please refer to this API documentation.
Common Use Cases
- Monitor the status of recently uploaded deposits.
- Generate ingest audit reports.
- Validate deposit state and file count over time
- Identify the Deposit ID of a specific deposit..
- Utilize the Deposit ID in conjunction with the Files API to generate an itemized list of each deposit.
- Store deposit reports locally alongside other collection metadata.
Response Schema
| Field | Description | Example |
|---|---|---|
| deposit_id | ID of the deposit | 42 |
| state | State describing the progress of the deposit | REPLICATED |
| user | Username of the User who created the deposit | UserName |
| registered_at | The instant at which your deposit is created. | Date-Time |
| file_count | Number of files and folders created in the deposit | 300 |
| size | Sum of the size of all files created in the deposit, in bytes | 4294967296 |
| collection_id | ID of the Collection to which the deposit was made. | 1024 |
| collection_name | Friendly name of the Collection to which the deposit was made | “Newspapers” |
Files API
Endpoint
GET /api/v1/files
Description
Retrieve a detailed inventory of folders and files within a deposit or a collection.
Returns a list of all files associated with a given deposit or collection, including file paths, size, checksums, and storage details. For more detailed technical information, please refer to this API documentation.
Parameters
- collection_id (optional)
- deposit_id (optional)
Common Use Cases
- Retrieve a complete inventory of archived files.
- Verify checksums and replica health.
- Identify large or missing files.
- Use in conjunction with the Collection ID to create inventory lists by Collection.
- Maintain master lists of preservation version file storage locations.
- Use in conjunction with the Deposit ID to generate Deposit Reports with detailed information for each file, including checksums.
- Attach detailed deposit reports to the final reports submitted for grant projects.
- Maintain local records of item-level checksums.
Response Schema
| Field | Description | Example |
|---|---|---|
| path | Path identifying the location of your content in Vault | “/Collection/Folder/file name” |
| size | Size of the file in bytes | 22867492 |
| file_count | Count of files within this file. | Always 1 for file-type; 0 or more for folder-type. |
| created_at | Instant at which the file was created | Date-time |
| type | Description of the type of file | “File” or “Folder” |
| permalink | Permanent location URL | https://vault.archiveit.org/details/82987 |
| md5 | Computed MD5 digest of the content | 11e9002c1e363ade25bef213f8298f73 |
| sha1 | Computed SHA1 digest of the content | f21620bf1194ab02d436968dbe3d298f39456175 |
| sha256 | Computed SHA256 digest of the content | 23a6db789be5ce1df48a4e5cadc2fbf74842a65812476df5ef0aa367fbd959d6 |
Fixity Report Summary API
Endpoint
GET /api/v1/reports/fixity
Description
Get summaries for many fixity reports. To see full report details, use the Get Fixity Report with the Report IDs returned by this endpoint. For more technical information, please refer to this API documentation.
Common Use Cases
- Identify the Report ID of a specific collection.
- Utilize the Report ID in conjunction with the Get Fixity Report API to generate detailed collection-level fixity reports.
- Review fixity check summaries for all your collections.
- Identify Collections with files that may require attention (e.g., failed or missing checks)
- Maintain records of successful periodic integrity scans.
Response Schema
| Field | Description | Example |
|---|---|---|
| report_id | ID number of a specific report. Used in the “Get Fixity Report” API. | 2705 |
| report_type | FIXITY | FIXITY |
| report_schema | Schema identifier for the detailed fixity report. | “:fixity-report-instance-schema:vault-global:” |
| collection_id | ID of the Collection to which the deposit was made | 1024 |
| collection_name | Friendly name of the Collection to which the deposit was made | “Newspapers” |
| file_count | Count of files checked in this report | 0 or more |
| total_size_bytes | Total size of all checked files in bytes | 22867492 |
| error_count | Count of errors in checked files | 0 or more |
| created_at | Date and time the report is generated | Date-time |
Fixity Report API
Endpoint
GET /api/v1/reports/fixity/{report_id}
Description
Download full details of individual fixity reports. Obtain Report IDs from the List Fixity Report Summary API endpoint. For more technical information, please refer to this API documentation.
Returns fixity validation results for files within a specified collection. These reports indicate whether file replicas remain unchanged over time.
Common Use Cases
- Identify the Report ID of a specific collection.
- Utilize in conjunction with the Report ID List Fixity Report Summary API to generate detailed collection-level fixity reports.
- Review fixity check results for integrity audits
- Identify files that may require attention (e.g., failed or missing checks)
- Validate the success of periodic integrity scans
Response Schema
| Field | Description | Example |
|---|---|---|
| report_id | ID number of a specific report. Used in the “Get Fixity Report” API. | 2705 |
| report_type | FIXITY | FIXITY |
| report_schema | Schema identifier for the detailed fixity report. | “:fixity-report-instance-schema:vault-global:” |
| Report | Representation of the body of a FIXITY-type report, version 2. | |
| generated_at | Date Time | |
| file_count | Count of files checked in this report | 0 or more |
| total_size | Total size of all checked files in bytes | 22867492 |
| collection_id | ID of the Collection to which the deposit was made | 1024 |
| collection_name | Friendly name of the Collection to which the deposit was made | “Newspapers” |
| report_frequency | Frequency of fixity reports for this account | Twice yearly |
| outcome_counts |
#0"NEW" #1"INPROGRESS" #2"PASSED" #3"FAILED" #4"ERROR" #5"REPAIRED" |
|
| files | Representation of the fixity checks corresponding to a given item and its constituent replicas. | |
| replica_checks | Representation of a fixity check of a single replica |
Notes and Best Practices
- Pagination is supported via limit and next_cursor
- Dates follow ISO 8601 format: YYYY-MM-DDThh:mm:ss.fffUTC
- The API is read-only and safe to explore
- The Open API specification is a standard format for describing REST APIs. By using the /api/v1/openapi.json listed at the top of the API documentation, you can interface with our API in the language of your choice using tools that generate code, client libraries, or documentation from the OAS definition.
For questions or extended use cases, submit a support request or contact: vault@archive.org.
Comments
Please sign in to leave a comment.