API docs by Redocly

Permanent Core API (1.0.0)

Download OpenAPI specification:

License: AGPL-3.0

authentication

Log in to the Permanent API. May require two-factor authentication. (not yet implemented)

Request Body schema: application/json
email
required
string
password
required
string
applicationId
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "applicationId": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Exchange a code for an authentication JWT at the conclusion of the OAuth process (not yet implemented)

Request Body schema: application/json
applicationId
required
string
applicationSecret
required
string
code
required
string

The code received from the OAuth login page

redirectUri
required
string <uri>

The same redirect URI passed to the OAuth login page

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "applicationSecret": "string",
  • "code": "string",
  • "redirectUri": "http://example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Start two-factor authentication (not yet implemented)

Start two-factor authentication as part of the login process, or in order to add or delete an MFA method. Requires authentication when adding or deleting an MFA method, but not during login (since at that point the user is not yet authenticated).

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
twoFactorId
string

Required when starting two-factor authentication as part of the login process.

methodId
string

Required when starting two-factor authentication as part of the login process, or in order to delete an MFA method.

destination
string

The "address" to which the two-factor code will be sent. This could be an email address or a phone number. Required when sending a two-factor code to a new device in order to add an MFA method

method
string
Enum: "sms" "email"

Required when sending a two-factor code to a new device in order to add an MFA method

Responses

Request samples

Content type
application/json
{
  • "twoFactorId": "string",
  • "methodId": "string",
  • "destination": "string",
  • "method": "sms"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Complete two-factor authentication (not yet implemented)

Request Body schema: application/json
twoFactorId
required
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "twoFactorId": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Log out of the Permanent API (not yet implemented)

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

unimplemented

Log in to the Permanent API. May require two-factor authentication. (not yet implemented)

Request Body schema: application/json
email
required
string
password
required
string
applicationId
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "applicationId": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Exchange a code for an authentication JWT at the conclusion of the OAuth process (not yet implemented)

Request Body schema: application/json
applicationId
required
string
applicationSecret
required
string
code
required
string

The code received from the OAuth login page

redirectUri
required
string <uri>

The same redirect URI passed to the OAuth login page

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "applicationSecret": "string",
  • "code": "string",
  • "redirectUri": "http://example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Start two-factor authentication (not yet implemented)

Start two-factor authentication as part of the login process, or in order to add or delete an MFA method. Requires authentication when adding or deleting an MFA method, but not during login (since at that point the user is not yet authenticated).

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
twoFactorId
string

Required when starting two-factor authentication as part of the login process.

methodId
string

Required when starting two-factor authentication as part of the login process, or in order to delete an MFA method.

destination
string

The "address" to which the two-factor code will be sent. This could be an email address or a phone number. Required when sending a two-factor code to a new device in order to add an MFA method

method
string
Enum: "sms" "email"

Required when sending a two-factor code to a new device in order to add an MFA method

Responses

Request samples

Content type
application/json
{
  • "twoFactorId": "string",
  • "methodId": "string",
  • "destination": "string",
  • "method": "sms"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Complete two-factor authentication (not yet implemented)

Request Body schema: application/json
twoFactorId
required
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "twoFactorId": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Log out of the Permanent API (not yet implemented)

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Add a new MFA method (not yet implemented)

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
method
required
string
Enum: "sms" "email"
destination
required
string (mfaDestination)

The "address" to which the two-factor code will be sent. This could be an email address or a phone number.

validationCode
required
string

The validation code that was sent to the user via the /start-mfa endpoint. Required to verify that the user has access to the specified destination.

Responses

Request samples

Content type
application/json
{
  • "method": "sms",
  • "destination": "string",
  • "validationCode": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "sms",
  • "destination": "string"
}

Delete an MFA method (not yet implemented)

Authorizations:
bearerHttpAuthentication
path Parameters
methodId
required
string

The ID of the MFA method to delete

Request Body schema: application/json
validationCode
required
string

The validation code that was sent to the user via the /start-mfa endpoint. Required to verify that the user has access to the specified destination.

Responses

Request samples

Content type
application/json
{
  • "validationCode": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a new account (not yet implemented)

Request Body schema: application/json
email
required
string
password
required
string
name
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Register a new application to use the Permanent API. Authorization token must belong to a registered developer account. (not yet implemented)

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
redirectUris
Array of strings <uri> [ items <uri > ]
scopes
required
Array of strings (applicationScope)
Items Enum: "record.create" "folder.view" "folder.create" "archive.view" "archive.create" "storage.view"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get application data by ID. Authorization token must belong to a registered developer account. (not yet implemented)

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string

An application ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an application. Authorization token must belong to a registered developer account. (not yet implemented)

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string

An application ID

Request Body schema: application/json
scopes
required
Array of strings (applicationScope)
Items Enum: "record.create" "folder.view" "folder.create" "archive.view" "archive.create" "storage.view"
redirectUris
Array of strings <uri> [ items <uri > ]

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an application. Authorization token must belong to a registered developer account. (not yet implemented)

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string

An application ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Create a new developer account (not yet implemented)

Request Body schema: application/json
email
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get an account's notification's. Notifications will be sorted in reverse chronological order (not yet implemented)

Authorizations:
bearerHttpAuthentication
query Parameters
cursor
string

The id of the notification right before the first notification you want returned. In most cases, this will be that of the last item on the previous page.

pageSize
required
integer

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Update a notification's status. Legal updates are new->seen, new->read, and seen->read (not yet implemented)

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
status
string
Enum: "seen" "read"

Responses

Request samples

Content type
application/json
{
  • "status": "seen"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

mfa-management

Start two-factor authentication (not yet implemented)

Start two-factor authentication as part of the login process, or in order to add or delete an MFA method. Requires authentication when adding or deleting an MFA method, but not during login (since at that point the user is not yet authenticated).

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
twoFactorId
string

Required when starting two-factor authentication as part of the login process.

methodId
string

Required when starting two-factor authentication as part of the login process, or in order to delete an MFA method.

destination
string

The "address" to which the two-factor code will be sent. This could be an email address or a phone number. Required when sending a two-factor code to a new device in order to add an MFA method

method
string
Enum: "sms" "email"

Required when sending a two-factor code to a new device in order to add an MFA method

Responses

Request samples

Content type
application/json
{
  • "twoFactorId": "string",
  • "methodId": "string",
  • "destination": "string",
  • "method": "sms"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Add a new MFA method (not yet implemented)

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
method
required
string
Enum: "sms" "email"
destination
required
string (mfaDestination)

The "address" to which the two-factor code will be sent. This could be an email address or a phone number.

validationCode
required
string

The validation code that was sent to the user via the /start-mfa endpoint. Required to verify that the user has access to the specified destination.

Responses

Request samples

Content type
application/json
{
  • "method": "sms",
  • "destination": "string",
  • "validationCode": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "sms",
  • "destination": "string"
}

Delete an MFA method (not yet implemented)

Authorizations:
bearerHttpAuthentication
path Parameters
methodId
required
string

The ID of the MFA method to delete

Request Body schema: application/json
validationCode
required
string

The validation code that was sent to the user via the /start-mfa endpoint. Required to verify that the user has access to the specified destination.

Responses

Request samples

Content type
application/json
{
  • "validationCode": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

accounts

Create a new account (not yet implemented)

Request Body schema: application/json
email
required
string
password
required
string
name
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

storage

Adjust the storage available to an account. Requires admin authentication

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string
Request Body schema: application/json
storageAmount
required
integer

The amount of storage to add to the account, expressed as an integer number of GBs (this could be negative)

Responses

Request samples

Content type
application/json
{
  • "storageAmount": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

admin

Adjust the storage available to an account. Requires admin authentication

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string
Request Body schema: application/json
storageAmount
required
integer

The amount of storage to add to the account, expressed as an integer number of GBs (this could be negative)

Responses

Request samples

Content type
application/json
{
  • "storageAmount": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

records

Get records

Authorizations:
NonebearerHttpAuthenticationpermanentShareToken
query Parameters
recordIds
Array of strings

An array of record IDs to retrieve. At least one of recordIds or archiveId must be provided.

archiveId
string

An archive ID to filter records by. At least one of recordIds or archiveId must be provided.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get a single record by ID

Authorizations:
NonebearerHttpAuthenticationpermanentShareToken
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a record

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
integer
Request Body schema: application/json
displayName
string
locationId
integer
description
string
displayTime
string <edtf>

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "locationId": 0,
  • "description": "string",
  • "displayTime": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

folders

Get folders by their IDs

Authorizations:
NonebearerHttpAuthenticationpermanentShareToken
query Parameters
folderIds
required
Array of strings

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update a folder

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
integer
Request Body schema: application/json
displayDate
string <date-time>
displayEndDate
string <date-time>
displayTime
string <edtf>

Responses

Request samples

Content type
application/json
{
  • "displayDate": "2019-08-24T14:15:22Z",
  • "displayEndDate": "2019-08-24T14:15:22Z",
  • "displayTime": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the children of the folder with the given ID

Authorizations:
NonebearerHttpAuthenticationpermanentShareToken
path Parameters
id
required
string
query Parameters
cursor
string

The folderLinkId of the item right before the first item you want returned. In most cases, this will be that of the last item on the previous page.

pageSize
required
integer

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Get all the top-level shared folders in an archive

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

archives

Search and filter archives

Search for archives by name and/or filter by the authenticated user's archive membership role.

  • Unauthenticated requests return only public archives.
  • Admin-authenticated requests return public archives with owner contact information.
  • User-authenticated requests return public archives and archives of which the caller is a member.

When filtering by callerMembershipRole:

  • Requires authentication (returns 401 if unauthenticated)
  • Returns only archives where the user has one of the specified roles
  • Includes the user's callerMembershipRole for each returned archive
Authorizations:
NonebearerHttpAuthentication
query Parameters
searchQuery
string

Filter archives by name matching this search query. At least one of searchQuery or callerMembershipRole is required.

callerMembershipRole
Array of strings (archiveMembershipRole)
Items Enum: "viewer" "contributor" "editor" "curator" "manager" "owner"

Filter to archives where the authenticated user has one of the specified archive membership roles. Can be repeated to filter by multiple roles (OR logic). Requires authentication. At least one of searchQuery or callerMembershipRole is required.

pageSize
required
integer >= 1
cursor
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Update an archive

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
integer
Request Body schema: application/json
milestoneSortOrder
string
Enum: "chronological" "reverse_chronological"

Responses

Request samples

Content type
application/json
{
  • "milestoneSortOrder": "chronological"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

application

Register a new application to use the Permanent API. Authorization token must belong to a registered developer account. (not yet implemented)

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
redirectUris
Array of strings <uri> [ items <uri > ]
scopes
required
Array of strings (applicationScope)
Items Enum: "record.create" "folder.view" "folder.create" "archive.view" "archive.create" "storage.view"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get application data by ID. Authorization token must belong to a registered developer account. (not yet implemented)

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string

An application ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an application. Authorization token must belong to a registered developer account. (not yet implemented)

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string

An application ID

Request Body schema: application/json
scopes
required
Array of strings (applicationScope)
Items Enum: "record.create" "folder.view" "folder.create" "archive.view" "archive.create" "storage.view"
redirectUris
Array of strings <uri> [ items <uri > ]

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an application. Authorization token must belong to a registered developer account. (not yet implemented)

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string

An application ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Create a new developer account (not yet implemented)

Request Body schema: application/json
email
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

notifications

Get an account's notification's. Notifications will be sorted in reverse chronological order (not yet implemented)

Authorizations:
bearerHttpAuthentication
query Parameters
cursor
string

The id of the notification right before the first notification you want returned. In most cases, this will be that of the last item on the previous page.

pageSize
required
integer

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Update a notification's status. Legal updates are new->seen, new->read, and seen->read (not yet implemented)

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
status
string
Enum: "seen" "read"

Responses

Request samples

Content type
application/json
{
  • "status": "seen"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

feature-flags

Retrieve feature flags. If admin authentication is provided, retrieves all feature flags. If not, retrieves the names of global feature flags.

Authorizations:
NonebearerHttpAuthentication

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a feature flag

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a feature flag

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string <uuid>
Request Body schema: application/json
description
string
globallyEnabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "globallyEnabled": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a feature flag

Authorizations:
bearerHttpAuthentication
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

storage-purchases

Initiate a storage purchase using Stripe.

Authorizations:
bearerHttpAuthentication
Request Body schema: application/json
amountInUSD
required
integer

The amount of money to be used to purchase storage in US dollars

Responses

Request samples

Content type
application/json
{
  • "amountInUSD": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

events

Create an event

Records an event in the audit trail and publishes it to the event topic. Optionally tracks analytics data via Mixpanel. Requires either user or admin authentication.

Authorizations:
bearerHttpAuthenticationdelegatedCallAuthentication
Request Body schema: application/json
required
entity
required
string

The type of entity the event pertains to (e.g. "account", "record", "folder")

action
required
string

The action performed on the entity (e.g. "create", "update", "delete")

version
required
number

The version number of the event schema

entityId
required
string

The identifier of the entity the event pertains to

userAgent
string

The user agent string of the client. If omitted, the User-Agent request header is used.

required
object

Action-specific payload. May include an optional analytics object.

Responses

Request samples

Content type
application/json
{
  • "entity": "string",
  • "action": "string",
  • "version": 0,
  • "entityId": "string",
  • "userAgent": "string",
  • "body": {
    }
}

Response samples

Content type
application/json
{ }

Retrieve checklist events

Returns the status of onboarding checklist items for the authenticated user, indicating which tasks have been completed.

Authorizations:
bearerHttpAuthentication

Responses

Response samples

Content type
application/json
{
  • "checklistItems": [
    ]
}