Preservation API

Ask about this page View Markdown

Base URL: https://YOUR-SERVER/api. Send your API key in x-api-key where authentication is required. A key also needs the listed permission; your account's access rules still apply.

API guide · All endpoints · OpenAPI JSON

DELETE /preservation/packages/{id} — Remove a preservation package
GET /preservation/packages/{id}/download — Download a preservation package
GET /preservation/packages/{id}/items — Get a preservation package item report
GET /preservation/packages/{id}/manifest — Download a preservation manifest
POST /preservation/preview — Preview a preservation export
GET /preservation/restores/{id}/items — Get restoration items

Remove a preservation package

DELETE /api/preservation/packages/{id}

Deletes the package’s own copy on this server. Your library’s originals are never touched, and a package named on the server by an administrator is only forgotten.

Authentication: API key. Permission: asset.download.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

{
  "204": {
    "description": ""
  }
}

Download a preservation package

GET /api/preservation/packages/{id}/download

The package this server wrote, as one ZIP. A package holding Locked items needs an unlocked session. Verify the downloaded copy before relying on it.

Authentication: API key. Permission: asset.download.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

{
  "200": {
    "content": {
      "application/octet-stream": {
        "schema": {
          "format": "binary",
          "type": "string"
        }
      }
    },
    "description": ""
  }
}

Get a preservation package item report

GET /api/preservation/packages/{id}/items

Each item of the package with its state, last verification and checksum. Locked items are counted but not named until the session is unlocked.

Authentication: API key. Permission: asset.download.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string
`skip`	query	No	integer
`state`	query	No
`take`	query	No	integer
`verifyState`	query	No

Parameter types, defaults and constraints

Field definitions: PreservationItemState, PreservationVerifyState

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "skip",
    "required": false,
    "in": "query",
    "schema": {
      "minimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    }
  },
  {
    "name": "state",
    "required": false,
    "in": "query",
    "schema": {
      "$ref": "#/components/schemas/PreservationItemState"
    }
  },
  {
    "name": "take",
    "required": false,
    "in": "query",
    "schema": {
      "minimum": 1,
      "maximum": 200,
      "type": "integer"
    }
  },
  {
    "name": "verifyState",
    "required": false,
    "in": "query",
    "schema": {
      "$ref": "#/components/schemas/PreservationVerifyState"
    }
  }
]

Responses

Field definitions: PreservationItemsResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PreservationItemsResponseDto"
        }
      }
    },
    "description": ""
  }
}

Download a preservation manifest

GET /api/preservation/packages/{id}/manifest

The manifest of a package this server wrote.

Authentication: API key. Permission: asset.download.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

{
  "200": {
    "content": {
      "application/octet-stream": {
        "schema": {
          "format": "binary",
          "type": "string"
        }
      }
    },
    "description": ""
  }
}

Preview a preservation export

POST /api/preservation/preview

How many of your items a selection holds, how large they are, whether they fit in one package and what a restoration brings back. Writes nothing.

Authentication: API key. Permission: asset.download.

Request body

Required.

Field definitions: PreservationPreviewDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PreservationPreviewDto"
    }
  }
}

Responses

Field definitions: PreservationPreviewResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PreservationPreviewResponseDto"
        }
      }
    },
    "description": ""
  }
}

Get restoration items

GET /api/preservation/restores/{id}/items

What the review found for each item — new, already in your library, or in the trash — the fields that disagree, your choices and what the restore left for you to look at.

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
`filter`	query	No
`id`	path	Yes	string
`skip`	query	No	integer
`take`	query	No	integer

Parameter types, defaults and constraints

Field definitions: PreservationRestoreItemFilter

[
  {
    "name": "filter",
    "required": false,
    "in": "query",
    "schema": {
      "$ref": "#/components/schemas/PreservationRestoreItemFilter"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "skip",
    "required": false,
    "in": "query",
    "schema": {
      "minimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    }
  },
  {
    "name": "take",
    "required": false,
    "in": "query",
    "schema": {
      "minimum": 1,
      "maximum": 200,
      "type": "integer"
    }
  }
]

Responses

Field definitions: PreservationRestoreItemsResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PreservationRestoreItemsResponseDto"
        }
      }
    },
    "description": ""
  }
}

Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.