Package sets API

You can use the Package sets API to put packages that belong together in a named package set, and share it with other people. The packages stay where they are in the archive, and one package can be in several package sets. All paths start with /v2, and every call needs the headers in Common headers.

You don't need a specific role to create package sets and work with them. What you can do with a package set depends on your permission on it: Read, ReadCanCollect, ReadWrite, or Everything.

Tip: To run a preservation action on the packages in a package set, list the set's packages, and then send their package IDs to the Preservation actions API.

List package sets

Returns the package sets that you have access to, sorted by title.

GET /v2/package-sets

Required role: none. You only get the package sets that you can read.

Response: 200 OK with a PackageSetList.

Create a package set

Creates an empty package set. Your username becomes its owner.

POST /v2/package-sets

Required role: none

{
  "title": "Board minutes 2019",
  "description": "Minutes and annexes of the 2019 board meetings."
}

Response: 200 OK with the PackageSet that the archive created, including its id.

• 400 Bad Request: title is missing.

Get a package set

Returns one package set.

GET /v2/package-sets/{packageSetId}

Required role: none. You need access to the package set.

Response: 200 OK with a PackageSet.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Update a package set

Changes the title or the description of a package set. If you leave out description, it keeps its value.

PUT /v2/package-sets/{packageSetId}

Required role: none. Your permission on the package set must allow changes.

Response: 200 OK with the updated PackageSet.

• 400 Bad Request: title is missing.

• 403 Forbidden: you can read the package set, but you can't change it.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Delete a package set

Deletes a package set.

DELETE /v2/package-sets/{packageSetId}

Required role: none. Your permission on the package set must allow deleting it.

Response: 204 No Content.

• 403 Forbidden: you can read the package set, but you can't delete it.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

List the packages in a package set

Returns the packages in a package set that you can read, in the same shape as a package in search results. Packages in the trash and packages that you can't read aren't in the list, so totalResults can be lower than the package set's memberCount.

GET /v2/package-sets/{packageSetId}/members

Required role: none. You need access to the package set.

Response: 200 OK with a PackageSetMemberList.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Add packages to a package set

Adds one or more packages to a package set. You name the packages by their package ID.

POST /v2/package-sets/{packageSetId}/members
POST /v2/package-sets/{packageSetId}/members/bulk

Both paths take the same body and do the same thing, so you can use either.

Required role: none. Your permission on the package set must allow adding packages.

{
  "documentIds": ["HR-2019-0042", "HR-2019-0043"]
}

The archive adds the packages one at a time, in the order that you send them. If it can't find a package, the call stops there with 404 Not Found, and the packages before it stay in the package set. The API sets no separate limit on the number of package IDs, other than the maximum request size.

Response: 204 No Content.

• 400 Bad Request: documentIds is missing.

• 403 Forbidden: you can read the package set, but you can't add packages to it.

• 404 Not Found: there's no package set with this ID, you don't have access to it, or one of the packages doesn't exist or you can't read it.

Remove a package from a package set

Takes one package out of a package set. The package itself stays in the archive.

DELETE /v2/package-sets/{packageSetId}/members/{documentId}

Required role: none. Your permission on the package set must allow removing packages.

Response: 204 No Content.

• 403 Forbidden: you can read the package set, but you can't remove packages from it.

• 404 Not Found: there's no package set with this ID, you don't have access to it, or the package doesn't exist or you can't read it.

Share a package set

You can share a package set with users and groups, with everyone who signs in, or by email with a person outside the archive. Each of these calls returns the package set's permissions as they are after the change.

To change permissions, you need the archive-content-manager role and Everything on the package set.

Get the permissions

Returns who has access to the package set, and whether it's public.

GET /v2/package-sets/{packageSetId}/permissions

Required role: none. You need access to the package set.

Response: 200 OK with a PackageSetPermissionList.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Give a user or a group access

Adds one permission for a user or a group. The other permissions on the package set don't change.

POST /v2/package-sets/{packageSetId}/permissions

Required role: archive-content-manager

{
  "principal": "jdoe",
  "permission": "Read",
  "timeframe": {
    "end": "2026-12-31T23:00:00Z"
  },
  "notify": true,
  "comment": "Here are the 2019 board minutes."
}

Response: 200 OK with a PackageSetPermissionList.

• 400 Bad Request with the reason INVALID_VALUE: the principal is Everyone, or an email share. To manage those, use Make a package set public and Share with someone by email.

• 403 Forbidden: you don't have Everything on the package set, or permission isn't one of the four values.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Remove a user's or a group's access

Removes the permissions that a user or a group has on the package set itself. Access that comes from elsewhere, with the INHERITED source, doesn't change.

DELETE /v2/package-sets/{packageSetId}/permissions?principal={principal}&permission={permission}

Required role: archive-content-manager

Response: 200 OK with a PackageSetPermissionList. If you removed your own access and it was your only access, the response has no entries and public is false.

• 400 Bad Request with the reason INVALID_VALUE: the principal is Everyone, or an email share.

• 403 Forbidden: you don't have Everything on the package set.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Make a package set public

Lets everyone who signs in to the archive view the package set, or takes that access away again.

PUT /v2/package-sets/{packageSetId}/permissions/public

Required role: archive-content-manager

{
  "public": true
}

Response: 200 OK with a PackageSetPermissionList, with public set.

• 403 Forbidden: you don't have Everything on the package set.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Share with someone by email

Gives a person access to the package set for a limited time, with their email address. They don't need an account in the archive, and the archive sends them an email about the share.

POST /v2/package-sets/{packageSetId}/permissions/share

Required role: archive-content-manager

{
  "email": "auditor@example.com",
  "permission": "Read",
  "timeframe": {
    "end": "2026-11-30T23:00:00Z"
  },
  "comment": "Here are the board minutes for your review."
}

Response: 200 OK with a PackageSetPermissionList. The share shows as an entry with the EXTERNAL source.

• 400 Bad Request with the reason REQUIRED_FIELD: timeframe or timeframe.end is missing.

• 403 Forbidden: you don't have Everything on the package set.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Stop sharing with someone by email

Removes every share with this email address on the package set.

DELETE /v2/package-sets/{packageSetId}/permissions/share?email={email}

Required role: archive-content-manager

Response: 200 OK with a PackageSetPermissionList.

• 403 Forbidden: you don't have Everything on the package set.

• 404 Not Found with the reason PACKAGE_SET_NOT_FOUND: there's no package set with this ID, or you don't have access to it.

Schemas

PackageSet

PackageSetList

PackageSetMemberList

PackageSetPermissionList

PermissionEntry