Archives
The Archives API helps you create and manage archives.
The base resource for this API is https://api.perma.cc/v1/archives/
Create an archive
Use POST to create a new archive.
Include the URL as JSON-encoded data.
curl -H "Authorization: ApiKey your-api-key" -H 'Content-Type: application/json' -X POST -d '{"url": "http://example.com"}' https://api.perma.cc/v1/archives/
Optional: to create an archive in a specific folder, include the folder's ID number in the JSON-encoded data. This should be a single integer, even for nested folders. The example below creates an archive in folder 1, and then another in folder 27 (a subfolder of folder 1). If you don't specify a folder ID, your archive will be created in your "Personal Links" folder.
Optional: you may provide a short "title" for the archive in the JSON-encoded data. If you do not specify a title, Perma will attempt to retrieve a title from the contents of the archived URL.
curl -H "Authorization: ApiKey your-api-key" -H 'Content-Type: application/json' -X POST -d '{"url": "http://example.com", "title": "This is an example site", "folder": 1}' https://api.perma.cc/v1/archives/
curl -H "Authorization: ApiKey your-api-key" -H 'Content-Type: application/json' -X POST -d '{"url": "http://example.com", "title": "This is another example site", "folder": 27}' https://api.perma.cc/v1/archives/
The response includes detailed information about the newly created archive, including the globally unique ID (GUID) of the archive:
{"guid":"85LS-BXV7","creation_timestamp":"2018-05-16T16:11:19.516152Z","url":"http://example.com","title":"This is an example site","description":null,"warc_size":null,"warc_download_url":"https://api.perma.cc/v1/archives/85LS-BXV7/download","captures":[{"role":"primary","status":"success","url":"http://example.com","record_type":"response","content_type":"text/html","user_upload":false},{"role":"screenshot","status":"success","url":"file:///85LS-BXV7/cap.png","record_type":"resource","content_type":"image/png","user_upload":false}],"queue_time":null,"capture_time":null,"notes":"","created_by":{"id":3,"first_name":"Jane","last_name":"Doe","full_name":"Jane Doe","short_name":"Jane"},"is_private":false,"private_reason":null,"user_deleted":false,"archive_timestamp":"2018-05-17T16:11:19.516152Z","organization":null}
Note that finalized details about an archive may not be available immediately: fields will update until the archiving process is complete. Use the Capture Job API and additional Archives API endpoints to get up-to-date details about a GUID.
To create many archives at once, use the Archives API endpoints for Batches
View the details of one archive
Use GET to retrieve details about an archive owned by you or by one of your organizations. More details are available via this authenticated Archives endpoint than are available from the non-authenticated Public Archives endpoint.
curl -H "Authorization: ApiKey your-api-key" https://api.perma.cc/v1/archives/85LS-BXV7/
Response:
{"guid":"85LS-BXV7","creation_timestamp":"2018-05-16T16:11:19Z","url":"http://example.com","title":"This is an example site","description":null,"warc_size":20924,"warc_download_url":"https://api.perma.cc/v1/archives/85LS-BXV7/download","captures":[{"role":"primary","status":"success","url":"http://example.com","record_type":"response","content_type":"text/html","user_upload":false},{"role":"screenshot","status":"success","url":"file:///85LS-BXV7/cap.png","record_type":"resource","content_type":"image/png","user_upload":false}],"queue_time":0,"capture_time":3,"notes":"","created_by":{"id":3,"first_name":"Jane","last_name":"Doe","full_name":"Jane Doe","short_name":"Jane"},"is_private":false,"private_reason":null,"user_deleted":false,"archive_timestamp":"2018-05-17T16:11:19Z","organization":null}
Download a single archive
Perma archives are downloadable and can be viewed using tools that can replay WARC files, like Rhizome's Webrecorder Player.
wget --header "Authorization: ApiKey your-api-key" https://api.perma.cc/v1/archives/Y6JJ-TDUJ/download
or
curl -H "Authorization: ApiKey your-api-key" -o your_favorite_filename.warc.gz https://api.perma.cc/v1/archives/Y6JJ-TDUJ/download
Make an archive private
Use PATCH to make an archive private.
Include the GUID of the archive in the URL, and set the archive's "is_private" field to true using JSON-encoded data:
curl -H "Authorization: ApiKey your-api-key" -H 'Content-Type: application/json' -X PATCH -d '{"is_private": true}' https://api.perma.cc/v1/archives/85LS-BXV7/
Response:
{"guid":"85LS-BXV7","creation_timestamp":"2018-05-16T16:11:19Z","url":"http://example.com","title":"This is an example site","description":null,"warc_size":20924,"warc_download_url":"https://api.perma.cc/v1/archives/85LS-BXV7/download","captures":[{"role":"primary","status":"success","url":"http://example.com","record_type":"response","content_type":"text/html","user_upload":false},{"role":"screenshot","status":"success","url":"file:///85LS-BXV7/cap.png","record_type":"resource","content_type":"image/png","user_upload":false}],"queue_time":0,"capture_time":3,"notes":"","created_by":{"id":3,"first_name":"Jane","last_name":"Doe","full_name":"Jane Doe","short_name":"Jane"},"is_private":true,"private_reason":"user","user_deleted":false,"archive_timestamp":"2018-05-17T16:11:19Z","organization":null}
Edit the title and notes fields of an archive
Use PATCH to change an archive's notes or title field.
Include the GUID of the archive in the URL, and specify your desired changes using JSON-encoded data:
curl -H "Authorization: ApiKey your-api-key" -H 'Content-Type: application/json' -X PATCH -d '{"title": "My updated title"}' https://api.perma.cc/v1/archives/85LS-BXV7/
Response:
{"guid":"85LS-BXV7","creation_timestamp":"2018-05-16T16:11:19Z","url":"http://example.com","title":"My updated title","description":null,"warc_size":20924,"warc_download_url":"https://api.perma.cc/v1/archives/85LS-BXV7/download","captures":[{"role":"primary","status":"success","url":"http://example.com","record_type":"response","content_type":"text/html","user_upload":false},{"role":"screenshot","status":"success","url":"file:///85LS-BXV7/cap.png","record_type":"resource","content_type":"image/png","user_upload":false}],"queue_time":0,"capture_time":3,"notes":"","created_by":{"id":3,"first_name":"Jane","last_name":"Doe","full_name":"Jane Doe","short_name":"Jane"},"is_private":true,"private_reason":"user","user_deleted":false,"archive_timestamp":"2018-05-17T16:11:19Z","organization":null}
Move an archive
Use PUT to move an archive into a different folder.
Include the ID of the destination folder as the first variable in the URL and the GUID of the archive as the second. The below example moves 85LS-BXV7 into folder 31.
curl -H "Authorization: ApiKey your-api-key" -X PUT https://api.perma.cc/v1/folders/31/archives/85LS-BXV7/
Response:
{"guid":"85LS-BXV7","creation_timestamp":"2018-05-16T16:11:19Z","url":"http://example.com","title":"My updated title","description":null,"warc_size":20924,"warc_download_url":"https://api.perma.cc/v1/archives/85LS-BXV7/download","captures":[{"role":"primary","status":"success","url":"http://example.com","record_type":"response","content_type":"text/html","user_upload":false},{"role":"screenshot","status":"success","url":"file:///85LS-BXV7/cap.png","record_type":"resource","content_type":"image/png","user_upload":false}],"queue_time":0,"capture_time":3,"notes":"","created_by":{"id":3,"first_name":"Jane","last_name":"Doe","full_name":"Jane Doe","short_name":"Jane"},"is_private":true,"private_reason":"user","user_deleted":false,"archive_timestamp":"2018-05-17T16:11:19Z","organization":{"id":3,"name":"A Third Journal","registrar":"Test Library","default_to_private":true,"shared_folder":{"id":31,"name":"A Third Journal","parent":null,"has_children":true,"path":"31","organization":3}}}
Delete an archive
Use DELETE to delete an archive.
curl -H "Authorization: ApiKey your-api-key" -X DELETE https://api.perma.cc/v1/archives/7J9R-2QM5/
This request deleted the archive. There will be no content in the HTTP response. You will see the a 204 HTTP status code returned.
No response data. HTTP status will be 204.
View all archives
Use GET to list all the archives you have access to.
This includes both public and private archives and includes all folders. (We're limiting ourselves to just 1 result to keep this example short.)
curl -H "Authorization: ApiKey your-api-key" https://api.perma.cc/v1/archives/?limit=1
Response:
{"meta":{"limit":1,"next":"https://api.perma.cc/v1/archives/?limit=1&offset=1","offset":0,"previous":null,"total_count":147},"objects":[{"guid":"F9BV-XLHU","creation_timestamp":"2018-05-05T23:03:41Z","url":"http://example.com","title":"example.com","description":"","warc_size":null,"warc_download_url":"https://api.perma.cc/v1/archives/F9BV-XLHU/download","captures":[{"role":"primary","status":"success","url":"file:///F9BV-XLHU/upload.png","record_type":"resource","content_type":"image/png","user_upload":true}],"queue_time":null,"capture_time":null,"notes":"","created_by":{"id":1,"first_name":"Jane","last_name":"Doe","full_name":"Jane Doe","short_name":"Jane"},"is_private":true,"private_reason":"user","user_deleted":false,"archive_timestamp":"2018-05-06T23:03:41Z","organization":{"id":3,"name":"A Third Journal","registrar":"Test Library","default_to_private":true,"shared_folder":{"id":31,"name":"A Third Journal","parent":null,"has_children":true,"path":"31","organization":3}}}]}
To restrict the results to a single folder, use the Folders API endpoint.
Work with batches of archives
You can request the creation of multiple archives at once by creating a batch.
Use HTTP POST, and include a list of URLs and a target folder ID (mandatory) as JSON-encoded data.
curl -H "Authorization: ApiKey your-api-key" -H 'Content-Type: application/json' -X POST -d '{"urls": ["http://example.com", "http://example.com/page", "http://example.com/another-page"], "target_folder": 24}' https://api.perma.cc/v1/archives/batches
The response includes an ID number for the batch (268 in the example below) and a list of "Capture Jobs", one per submitted URL.
{"id":268,"started_on":"2018-05-16T17:46:14Z","created_by":3,"capture_jobs":[{"guid":"F42B-NZ6G","status":"pending","message":null,"submitted_url":"http://example.com","attempt":1,"step_count":0.0,"step_description":"","capture_start_time":"2018-05-16T17:46:14Z","capture_end_time":"2018-05-16T17:46:18Z","queue_position":0,"title":"Example Domain","user_deleted":false},{"guid":"48YX-LMW5","status":"completed","message":null,"submitted_url":"http://example.com/page","attempt":1,"step_count":6.0,"step_description":"Saving web archive file","capture_start_time":"2018-05-16T17:46:18Z","capture_end_time":"2018-05-16T17:46:21Z","queue_position":0,"title":"Example Domain","user_deleted":false},{"guid":"CH84-WDL3","status":"completed","message":null,"submitted_url":"http://example.com/another-page","attempt":1,"step_count":6.0,"step_description":"Saving web archive file","capture_start_time":"2018-05-16T17:46:21Z","capture_end_time":"2018-05-16T17:46:24Z","queue_position":0,"title":"Example Domain","user_deleted":false}],"target_folder": {"id": 24, "name": "A Third Journal", "parent": null, "has_children": true, "path": "24", "organization": 3},"links_remaining":45}
Capture Jobs report details about attempts to create archives. Review the list of Capture Jobs to find the GUIDS of successfully created archives and find validation error messages for any URLs that failed.
Note that finalized details about a batch are not available immediately: fields will update until the archiving process is complete.
Use GET to retrieve up-to-date details about a batch.
curl -H "Authorization: ApiKey your-api-key" https://api.perma.cc/v1/archives/batches/268
Use GET to retrieve a list of all your batches.
curl -H "Authorization: ApiKey your-api-key" https://api.perma.cc/v1/archives/batches