Perma.cc API for developers

API Overview

The Perma.cc API helps you create and manage archives without using your web browser.

The API is simple, but powerful. There are four endpoints available to you in the API, but you really only manipulate two "things," archives and folders. You can create and manage archives with the Archive endpoint, and you can organize your archives with Folders endpoint.

The other two endpoints, Public Archives and Users, are lenses into Archives and folders, limiting your views to Public archives, and archives and folders as managed by one user.

The API is RESTful and leverages the HTTP GET, POST, PUT, PATCH, and DELETE verbs.

Please let us know if you have suggestions or run into bugs in the API.

API Key

Many of the API endpoints will require you to use an API key. Find your API key in your Dashboard under the Settings, Tools section. Click on the Generate an API key button.

Create an API key

Pagination

The API will return 20 items per response. If you have more than 20 items returned, you can page through the items using the offset parameter. For example, if you want to start at the 101st result, set the offset value to 4 (we start counting at 0, of course).

curl https://api.perma.cc/v1/public/archives/?offset=4

If you'd prefer to get a smaller result set, specify the number of returned items using the limit parameter. In this example, we'll see just one item returned.

curl https://api.perma.cc/v1/public/archives/?limit=1

JSONP

When building applications in JavaScript you often have to be mindful of the browser's same origin policy. JSONP is a technique that is commonly used to communicate when a same origin policy is in place. Perma.cc API offers full supports for JSONP, just add a callback argument to your query string.

curl https://api.perma.cc/v1/public/archives/?api_key=your-api-key&callback=name-of-your-callback

Your response wrapped in your callback

name-of-your-callback(
  {
      "meta": {
          "limit": 1,
          "next": "/v1/public/archives/?limit=1&offset=1",
          "offset": 0,
          "previous": null,
          "total_count": 2
      },
      "objects": [
          {
              "assets": [
                  {
                      "base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ",
                      "favicon": null,
                      "image_capture": "cap.png",
                      "pdf_capture": null,
                      "warc_capture": "archive.warc.gz"
                  }
              ],
              "creation_timestamp": "2015-01-21T17:39:44Z",
              "is_private": true,
              "expiration_date": "2017-01-21T17:39:44Z",
              "guid": "Y6JJ-TDUJ",
              "title": "Example.com. yo.",
              "url": "http://example.com",
              "organization": {
                  "id": 1,
                  "name": "Test Journal"
              }
          }
      ]
  }
)

Examples in cURL

Our API documentation is example based, and our examples show you how to interact with the API using the cURL command line utility. A friendly tip - you can add the -v option to help debug your HTTP interactions.

curl https://api.perma.cc/v1/public/archives/?limit=1 -v

Public Archives

The Public Archives API endpoint helps you find all archives in publicly available Perma.cc archives. You do not need an API Key to use this portion of the API.

The base endpoint for this API is https://api.perma.cc/v1/public/archives/

Get all public archives

Use an HTTP GET to retrieve a every public archive in Perma.cc. (In order to keep this example short, we limit our number of returned items to one.)

curl https://api.perma.cc/v1/public/archives/?limit=1

Response

{"meta": {"limit": 1, "next": "/v1/public/archives/?limit=1", "offset": 0, "previous": null, "total_count": 2}, "objects": [{"assets": [{"base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ", "favicon": null, "image_capture": "cap.png", "pdf_capture": null, "warc_capture": "archive.warc.gz"}], "creation_timestamp": "2015-01-21T17:39:44Z", "is_private": true, "expiration_date": "2017-01-21T17:39:44Z", "guid": "Y6JJ-TDUJ", "title": "Example.com. yo.", "url": "http://example.com", "organization": {"id": 1, "name": "Test Journal"}}]}

Get one archive

If we have a the globally unique ID of one archive, we can GET details on it.

curl https://api.perma.cc/v1/public/archives/Y6JJ-TDUJ/

Response

{"assets": [{"base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ", "favicon": null, "image_capture": "cap.png", "pdf_capture": null, "warc_capture": "archive.warc.gz"}], "creation_timestamp": "2015-01-21T17:39:44Z", "is_private": true, "expiration_date": "2017-01-21T17:39:44Z", "guid": "Y6JJ-TDUJ", "title": "Example.com. yo.", "url": "http://example.com", "organization": {"id": 1, "name": "Test Journal"}}

Users

The Users API endpoint helps you gather information about one user's resources in Perma.cc. It's an easy way to see the breadth of Perma.cc, through the lens of a single user.

The base endpoint for this API is https://api.perma.cc/v1/user/

Get a user's account details

Use an HTTP GET to retrieve a user's profile

curl https://api.perma.cc/v1/user/?api_key=your-api-key

Response

{"first_name": "Jane", "full_name": "Jane Doe", "id": 4, "last_name": "Doe", "short_name": "Jane"}

Get a user's archives

GET all of the user's archives.

curl https://api.perma.cc/v1/user/archives/?limit=1&api_key=your-api-key

Response. (In order to keep this example short, we limit our number of returned items to one.)

{"meta": {"limit": 1, "next": "/v1/user/archives/?api_key=api_key=your-api-key&limit=1", "offset": 0, "previous": null, "total_count": 6}, "objects": [{"assets": [{"base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ", "favicon": null, "image_capture": "cap.png", "pdf_capture": null, "warc_capture": "archive.warc.gz"}], "created_by": {"first_name": "Regular", "full_name": "Regular User", "id": 4, "last_name": "User", "short_name": "Regular"}, "creation_timestamp": "2015-01-21T17:39:44Z", "is_private": true, "expiration_date": "2017-01-21T17:39:44Z", "guid": "Y6JJ-TDUJ", "notes": "", "title": "Example.com. yo.", "url": "http://example.com", "last_name": "User", "short_name": "Org"}, "organization": {"id": 1, "name": "Test Journal"}}]}

Get a user's folders

GET all of the user's folders.

curl https://api.perma.cc/v1/user/folders/?limit=1&api_key=your-api-key

Response.

{"meta": {"limit": 1, "next": "v1/user/folders/?api_key=your-api-key&limit=1", "offset": 0, "previous": null, "total_count": 8}, "objects": [{"id": 25, "name": "Personal Links", "parent": null}]}

Get a user's organizations

GET all of the orgs in which a user is a member.

curl https://api.perma.cc/v1/user/organizations/?limit=1&api_key=your-api-key

Response.

{"meta": {"limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 1}, "objects": [{"id": 1, "name": "Test Journal"}]}

Get a user's shared folders inside an organization

Orgs allow members to share folders. GET the org's list of shared folders.

curl https://api.perma.cc/v1/user/organizations/1/folders/?limit=1&api_key=your-api-key

Response.

{"meta": {"limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 1}, "objects": [{"id": 27, "name": "Test Journal", "parent": null}]}

Get a user's ongoing capture jobs

List all of a user's pending or in_progress capture jobs.

curl -v https://api.perma.cc/v1/capture_jobs/?api_key=your-api-key

View capture status for a particular archive by GUID.

curl -v https://api.perma.cc/v1/capture_jobs/ABCD-1234/?api_key=your-api-key

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

Create a new archive by POSTing (as JSON) the URL and the Title.

curl -H 'Content-Type: application/json' -X POST -d '{"url": "http://example.com", "title": "This is an example site"}' https://api.perma.cc/v1/archives/?api_key=your-api-key

Create an archive in a specific folder (the folder id is 27 in this instance). If you don't include a folder id, your archive will be created in the "Personal Links" folder.

curl -H 'Content-Type: application/json' -X POST -d '{"url": "http://example.com", "title": "This is an example site", "folder": 27}' https://api.perma.cc/v1/archives/?api_key=your-api-key

Response includes detailed information about the newly created archive

{"assets": [{"base_storage_path": "2015/1/21/21/41/8H4S-TNRA", "favicon": null, "image_capture": "pending", "pdf_capture": null, "warc_capture": "pending"}], "created_by": {"first_name": "Regular", "full_name": "Regular User", "id": 4, "last_name": "User", "short_name": "Regular"}, "creation_timestamp": "2015-01-21T16:41:15Z", "is_private": false, "expiration_date": "2017-01-21T16:41:15Z", "folders": ["/v1/folders/25/"], "guid": "8H4S-TNRA", "notes": "", "title": "This is a test page", "url": "http://example.com", "organization": null}

View the details of one archive

curl https://api.perma.cc/v1/archives/Y6JJ-TDUJ/

This will show you details of an archive. Pass in the archive's globally unique ID using a GET request.

{"assets": [{"base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ", "favicon": null, "image_capture": "cap.png", "pdf_capture": null, "warc_capture": "archive.warc.gz"}], "created_by": {"first_name": "Regular", "full_name": "Regular User", "id": 4, "last_name": "User", "short_name": "Regular"}, "creation_timestamp": "2015-01-21T17:39:44Z", "is_private": false, "expiration_date": "2017-01-21T17:39:44Z", "folders": ["/v1/folders/25/"], "guid": "Y6JJ-TDUJ", "notes": "", "title": "Example Domain", "url": "http://example.com", "organization": null}

View all archives associated with one user

If you want to list all the archives associated with one user, route through the User endpoint. (The result set will contain a list of all the user's archives. We're limiting ourseleves to just 1 result to keep this example short.)

curl https://api.perma.cc/v1/user/archives/?api_key=your-api-key&limit=1

Pass in your API key using a GET.

{"meta": {"limit": 1, "next": "/v1/user/archives/?api_key=your-api-key&limit=1", "offset": 0, "previous": null, "total_count": 11}, "objects": [{"assets": [{"base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ", "favicon": null, "image_capture": "cap.png", "pdf_capture": null, "warc_capture": "archive.warc.gz"}], "created_by": {"first_name": "Regular", "full_name": "Regular User", "id": 4, "last_name": "User", "short_name": "Regular"}, "creation_timestamp": "2015-01-21T17:39:44Z", "is_private": true, "expiration_date": "2017-01-21T17:39:44Z", "folders": ["/v1/folders/25/", "/v1/folders/27/"], "guid": "Y6JJ-TDUJ", "notes": "", "title": "Example.com. yo.", "url": "http://example.com", "organization": {"id": 1, "name": "Test Journal"}}]}

Place an archive in the dark archive

You can dark archive an archive using by PATCHing it. Be sure to include the JSON object and the guid of archive in your request.

curl -H 'Content-Type: application/json' -X PATCH -d '{"is_private": "True"}' https://api.perma.cc/v1/archives/7J9R-2QM5/?api_key=your-api-key

Place an archive in the dark archive by setting the "is_private" field to "True". Pass in a JSON data object using PATCH, and the guid of archive.

{"assets": [{"base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ", "favicon": null, "image_capture": "cap.png", "pdf_capture": null, "warc_capture": "archive.warc.gz"}], "created_by": {"first_name": "Regular", "full_name": "Regular User", "id": 4, "last_name": "User", "short_name": "Regular"}, "creation_timestamp": "2015-01-21T17:39:44Z", "is_private": true, "expiration_date": "2017-01-21T17:39:44Z", "folders": ["/v1/folders/25/", "/v1/folders/27/"], "guid": "Y6JJ-TDUJ", "notes": "", "title": "Example.com. yo.", "url": "http://example.com", "organization": {"id": 1, "name": "Test Journal"}}

Edit the title and notes fields of an archive

Change the notes or title field by PATCHing the archive. Be sure to include the JSON object and the guid of archive in your request.

curl -H 'Content-Type: application/json' -X PATCH -d '{"title": "My updated title"}' https://api.perma.cc/v1/archives/Y6JJ-TDUJ/?api_key=your-api-key

Title and notes are the two editable fields. Here, we're just updating the notes field. Pass in a JSON data object using PATCH, and the guid of archive.

{"assets": [{"base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ", "favicon": null, "image_capture": "cap.png", "pdf_capture": null, "warc_capture": "archive.warc.gz"}], "created_by": {"first_name": "Regular", "full_name": "Regular User", "id": 4, "last_name": "User", "short_name": "Regular"}, "creation_timestamp": "2015-01-21T17:39:44Z", "is_private": false, "expiration_date": "2017-01-21T17:39:44Z", "folders": ["/v1/folders/25/"], "guid": "Y6JJ-TDUJ", "notes": "", "title": "Example.com. yo.", "url": "http://example.com", "organization": null}

Move an archive

Move an archive into a different folder using a PUT command

curl -X PUT https://api.perma.cc/v1/folders/33/archives/Y6JJ-TDUJ/?api_key=your-api-key -v

The response tells you that you've placed moved the archive into folder 33.

{"assets": [{"base_storage_path": "2015/1/21/22/39/Y6JJ-TDUJ", "favicon": null, "image_capture": "cap.png", "pdf_capture": null, "warc_capture": "archive.warc.gz"}], "created_by": {"first_name": "Regular", "full_name": "Regular User", "id": 4, "last_name": "User", "short_name": "Regular"}, "creation_timestamp": "2015-01-21T17:39:44Z", "is_private": true, "expiration_date": "2017-01-21T17:39:44Z", "folder": "33", "folders": ["/v1/folders/25/", "/v1/folders/33/"], "guid": "Y6JJ-TDUJ", "notes": "", "title": "Example.com. yo.", "url": "http://example.com", "organization": {"id": 1, "name": "Test Journal"}}

Delete an archive

Delete an archive using a DELETE.

curl -X DELETE https://api.perma.cc/v1/archives/7J9R-2QM5/?api_key=your-api-key

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. HTTP status will be 204.

Folders

The Folders API helps you create and manage folders.

The base resource for this API is https://api.perma.cc/v1/folders/

Create a folder

Create a new folder using a POST

curl -H 'Content-Type: application/json' -X POST -d '{"name": "a new folder"}' https://api.perma.cc/v1/folders/25/folders/?api_key=your-api-key

The response will include the id of the new folder and the folder's parent ID.

{"id": 35, "name": "a new folder", "parent": "/v1/folders/25/"}

View a folder's details

Use a GET to retrieve details of an existing folder.

curl -v "https://api.perma.cc/v1/folders/28/?api_key=your-api-key"

The response will include the id of the new folder and the folder's parent ID (the same response that you get when you create a new folder).

{"id": 35, "name": "a new folder", "parent": "/v1/folders/25/"}

Rename a folder

Use a PATCH to change a folder's name.

curl -H 'Content-Type: application/json' -X PATCH -d '{"name": "a new folder name"}' 'https://api.perma.cc/v1/folders/28/?api_key=your-api-key'

The response will include the new folder name.

{"id": 28, "name": "a new folder name", "parent": "/v1/folders/25/"}

Move a folder

Use a PUT to move a folder into another folder.

curl -H 'Content-Type: application/json' -X PUT https://api.perma.cc/v1/folders/35/folders/36/?api_key=your-api-key

This command moved folder 36 into folder 35. The response will include the folder's new parent id.

{"id": 36, "name": "just another folder", "parent": "/v1/folders/35/"}

Delete a folder

Use a DELETE to delete a folder.

curl -X DELETE https://api.perma.cc/v1/folders/36/?api_key=your-api-key

This command deleted folder 36. There will be no content in the HTTP response. You will see the a 204 HTTP status code returned.

No response. HTTP status will be 204.