Assets API

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

• GET /archive-operations — List recent archive operations
• POST /archive-operations — Archive a selection in the background
• POST /archive-operations/prepare — Count and freeze every matching Timeline asset
• GET /archive-operations/{id} — Retrieve an archive operation
• POST /archive-operations/{id}/confirm — Confirm a prepared archive selection
• POST /archive-operations/{id}/undo — Undo an archive operation
• DELETE /assets — Delete assets
• POST /assets — Upload asset
• PUT /assets — Update assets
• POST /assets/bulk-upload-check — Check bulk upload
• PUT /assets/copy — Copy asset
• POST /assets/jobs — Run an asset job
• POST /assets/lock — Lock assets
• DELETE /assets/metadata — Delete asset metadata
• PUT /assets/metadata — Upsert asset metadata
• GET /assets/statistics — Get asset statistics
• POST /assets/unlock — Unlock assets
• OPTIONS /assets/uploads — Get resumable asset upload limits
• POST /assets/uploads — Create resumable asset upload
• POST /assets/uploads/live-photo/commit — Commit two verified Live Photo upload resources atomically
• DELETE /assets/uploads/{id} — Cancel an unpublished upload
• HEAD /assets/uploads/{id} — Get durable upload offset
• PATCH /assets/uploads/{id} — Append immutable upload bytes
• GET /assets/uploads/{id}/result — Recover a completed upload result
• GET /assets/{id} — Retrieve an asset
• PUT /assets/{id} — Update an asset
• GET /assets/{id}/develop — List develop versions of an asset
• PUT /assets/{id}/develop — Save a develop recipe as a new version
• POST /assets/{id}/develop/artifacts — Upload a develop artifact
• GET /assets/{id}/develop/exports — List exports of an original for editing elsewhere
• POST /assets/{id}/develop/exports — Export an original for editing elsewhere
• POST /assets/{id}/develop/imports — Bring back a file developed elsewhere
• POST /assets/{id}/develop/masks/propose — Suggest a subject or sky mask locally
• POST /assets/{id}/develop/preview — Render a develop preview
• POST /assets/{id}/develop/revert — Revert to the original or an earlier develop version
• GET /assets/{id}/develop/revisions/{revisionId}/file — View a rendered develop file
• DELETE /assets/{id}/develop/revisions/{revisionId}/render — Cancel a develop render
• POST /assets/{id}/develop/revisions/{revisionId}/render — Render a develop version
• GET /assets/{id}/edit-versions — List saved video versions
• POST /assets/{id}/edit-versions/export — Export the current video version
• DELETE /assets/{id}/edit-versions/{versionId} — Prune an unselected video version
• GET /assets/{id}/edit-versions/{versionId}/download — Download a video version master
• POST /assets/{id}/edit-versions/{versionId}/restore — Restore a saved video version
• DELETE /assets/{id}/edits — Remove edits from an existing asset
• GET /assets/{id}/edits — Retrieve edits for an existing asset
• PUT /assets/{id}/edits — Apply edits to an existing asset
• GET /assets/{id}/edits/keyframes — List the original video's keyframes
• GET /assets/{id}/image-enrichment — Get image enrichment metadata
• PUT /assets/{id}/image-enrichment — Update image enrichment metadata
• GET /assets/{id}/metadata — Get asset metadata
• PUT /assets/{id}/metadata — Update asset metadata
• DELETE /assets/{id}/metadata/{key} — Delete asset metadata by key
• GET /assets/{id}/metadata/{key} — Retrieve asset metadata by key
• GET /assets/{id}/ocr — Retrieve asset OCR data
• GET /assets/{id}/original — Download original asset
• DELETE /assets/{id}/restorations/{restorationId} — Discard a restoration
• GET /assets/{id}/restorations/{restorationId}/file — View a restoration file
• GET /assets/{id}/thumbnail — View asset thumbnail
• GET /assets/{id}/video/playback — Play asset video
• GET /assets/{id}/video/stream/main.m3u8 — Get HLS main playlist
• DELETE /assets/{id}/video/stream/{sessionId} — End HLS streaming session
• GET /assets/{id}/video/stream/{sessionId}/{variantIndex}/playlist.m3u8 — Get HLS media playlist
• GET /assets/{id}/video/stream/{sessionId}/{variantIndex}/{filename} — Get HLS segment or init file
• GET /assets/{id}/video/studio-hdr — Play the Studio HDR intermediate
• GET /develop-presets — List develop presets
• POST /develop-presets — Save a develop preset
• DELETE /develop-presets/{id} — Delete a develop preset
• PUT /develop-presets/{id} — Update a develop preset
• GET /takeout — List Google Photos imports
• POST /takeout — Start a Google Photos import
• GET /takeout/roots — List the permitted import locations
• DELETE /takeout/{id} — Delete a Google Photos import
• GET /takeout/{id} — Get a Google Photos import
• POST /takeout/{id}/archives — Stage a Takeout archive
• DELETE /takeout/{id}/archives/{archiveId} — Remove a staged Takeout archive
• PUT /takeout/{id}/archives/{archiveId}/chunks — Upload part of a Takeout archive
• POST /takeout/{id}/archives/{archiveId}/verify — Check a staged part of a Takeout archive
• POST /takeout/{id}/control — Pause, resume or cancel a Google Photos import
• POST /takeout/{id}/import — Import the reviewed items
• GET /takeout/{id}/items — List the items of a Google Photos import
• PUT /takeout/{id}/items/{itemId} — Choose metadata for an item, or leave it out
• GET /takeout/{id}/live-photos — List possible Live Photos in a Google Photos import
• PUT /takeout/{id}/live-photos — Link or separate a possible Live Photo
• POST /takeout/{id}/scan — Scan a Google Photos import

List recent archive operations

GET /api/archive-operations

Authentication: API key. Permission: asset.update.

Responses

Field definitions: ArchiveOperationResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/ArchiveOperationResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Archive a selection in the background

POST /api/archive-operations

Freezes the selection and hands it to a durable bulk job. Undo later restores only items nothing has changed since.

Authentication: API key. Permission: asset.update.

Request body

Required.

Field definitions: ArchiveOperationCreateDto

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

Responses

Field definitions: ArchiveOperationResponseDto

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

Count and freeze every matching Timeline asset

POST /api/archive-operations/prepare

Counts and freezes, in one transaction, every asset of your own normal Timeline this session can see. Nothing changes until the count is confirmed.

Authentication: API key. Permission: asset.update.

Request body

Required.

Field definitions: ArchiveOperationPrepareDto

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

Responses

Field definitions: ArchiveOperationResponseDto

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

Retrieve an archive operation

GET /api/archive-operations/{id}

Authentication: API key. Permission: asset.update.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: ArchiveOperationResponseDto

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

Confirm a prepared archive selection

POST /api/archive-operations/{id}/confirm

Authentication: API key. Permission: asset.update.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: ArchiveOperationConfirmDto

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

Responses

Field definitions: ArchiveOperationResponseDto

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

Undo an archive operation

POST /api/archive-operations/{id}/undo

Restores, in the background, every item the archive changed that nothing has changed since. A running archive is stopped first.

Authentication: API key. Permission: asset.update.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: ArchiveOperationUndoDto

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

Responses

Field definitions: ArchiveOperationResponseDto

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

Delete assets

DELETE /api/assets

Deletes multiple assets at the same time.

Authentication: API key. Permission: asset.delete.

Request body

Required.

Field definitions: AssetBulkDeleteDto

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

Responses

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

Upload asset

POST /api/assets

Uploads a new asset to the server.

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
key	query	No	string
slug	query	No	string

Parameter types, defaults and constraints

[
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
]

Request body

Required. Asset Upload Information

Field definitions: AssetMediaCreateDto

{
  "multipart/form-data": {
    "schema": {
      "$ref": "#/components/schemas/AssetMediaCreateDto"
    }
  }
}

Responses

Field definitions: AssetMediaResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetMediaResponseDto"
        }
      }
    },
    "description": "Asset is a duplicate"
  },
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetMediaResponseDto"
        }
      }
    },
    "description": "Asset uploaded successfully"
  }
}

Update assets

PUT /api/assets

Updates multiple assets at the same time.

Deprecated. Avoid this operation in new integrations; use the replacement supported by your server release.

Authentication: API key. Permission: asset.update.

Request body

Required.

Field definitions: AssetBulkUpdateDto

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

Responses

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

Check bulk upload

POST /api/assets/bulk-upload-check

Determine which assets have already been uploaded to the server based on their SHA1 checksums.

Authentication: API key. Permission: asset.upload.

Request body

Required.

Field definitions: AssetBulkUploadCheckDto

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

Responses

Field definitions: AssetBulkUploadCheckResponseDto

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

Copy asset

PUT /api/assets/copy

Copy asset information like albums, tags, etc. from one asset to another.

Authentication: API key. Permission: asset.copy.

Request body

Required.

Field definitions: AssetCopyDto

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

Responses

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

Run an asset job

POST /api/assets/jobs

Run a specific job on a set of assets.

Authentication: API key. Permission: job.create.

Request body

Required.

Field definitions: AssetJobsDto

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

Responses

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

Lock assets

POST /api/assets/lock

Locks assets: they keep their albums and organization, are hidden from every view except the Locked view of their owner in a PIN-unlocked session, and stacks and live photos lock as a whole.

Authentication: API key. Permission: asset.update.

Request body

Required.

Field definitions: BulkIdsDto

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

Responses

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

Delete asset metadata

DELETE /api/assets/metadata

Delete metadata key-value pairs for multiple assets.

Authentication: API key. Permission: asset.update.

Request body

Required.

Field definitions: AssetMetadataBulkDeleteDto

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

Responses

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

Upsert asset metadata

PUT /api/assets/metadata

Upsert metadata key-value pairs for multiple assets.

Authentication: API key. Permission: asset.update.

Request body

Required.

Field definitions: AssetMetadataBulkUpsertDto

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

Responses

Field definitions: AssetMetadataBulkResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/AssetMetadataBulkResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Get asset statistics

GET /api/assets/statistics

Retrieve various statistics about the assets owned by the authenticated user.

Authentication: API key. Permission: asset.statistics.

Parameters

Name	Where	Required	Description
isFavorite	query	No	Filter by favorite status
isTrashed	query	No	Filter by trash status
visibility	query	No

Parameter types, defaults and constraints

Field definitions: AssetVisibility

[
  {
    "name": "isFavorite",
    "required": false,
    "in": "query",
    "description": "Filter by favorite status",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "isTrashed",
    "required": false,
    "in": "query",
    "description": "Filter by trash status",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "visibility",
    "required": false,
    "in": "query",
    "schema": {
      "$ref": "#/components/schemas/AssetVisibility"
    }
  }
]

Responses

Field definitions: AssetStatsResponseDto

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

Unlock assets

POST /api/assets/unlock

Unlocks assets the caller owns, whatever locked them, returning each exactly where it was. Requires a PIN-unlocked session.

Authentication: API key. Permission: asset.update.

Request body

Required.

Field definitions: BulkIdsDto

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

Responses

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

Get resumable asset upload limits

OPTIONS /api/assets/uploads

Authentication: API key. Permission: asset.upload.

Responses

{
  "204": {
    "description": "Resumable upload limits"
  }
}

Create resumable asset upload

POST /api/assets/uploads

IETF resumable upload draft 12 / interop 9 prerequisite. Single resources publish by default; explicitly declared Live Photo resources stay private until pair commit.

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
Asset-Metadata	header	Yes	Canonical base64url UTF-8 JSON: filename, fileCreatedAt, fileModifiedAt; optional duration (integer milliseconds), isFavorite (JSON boolean; the strings "true" and "false" are also accepted), visibility, metadata array and publication: live-photo to defer publication until atomic pair commit. No sidecar or pre-existing asset references.
Repr-Digest	header	Yes	RFC 9530 single sha-256=:base64: digest of the entire file, required before any publication
Upload-Complete	header	Yes	string
Upload-Draft-Interop-Version	header	Yes	string
Upload-Length	header	No	integer

Parameter types, defaults and constraints

[
  {
    "name": "Asset-Metadata",
    "in": "header",
    "description": "Canonical base64url UTF-8 JSON: filename, fileCreatedAt, fileModifiedAt; optional duration (integer milliseconds), isFavorite (JSON boolean; the strings \"true\" and \"false\" are also accepted), visibility, metadata array and publication: live-photo to defer publication until atomic pair commit. No sidecar or pre-existing asset references.",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "Repr-Digest",
    "in": "header",
    "description": "RFC 9530 single sha-256=:base64: digest of the entire file, required before any publication",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "Upload-Complete",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "enum": [
        "?0",
        "?1"
      ]
    }
  },
  {
    "name": "Upload-Draft-Interop-Version",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "enum": [
        "9"
      ]
    }
  },
  {
    "name": "Upload-Length",
    "in": "header",
    "required": false,
    "schema": {
      "type": "integer",
      "minimum": 1,
      "maximum": 2147483648
    }
  }
]

Request body

Required.

{
  "audio/*": {
    "schema": {
      "format": "binary",
      "type": "string"
    }
  },
  "image/*": {
    "schema": {
      "format": "binary",
      "type": "string"
    }
  },
  "video/*": {
    "schema": {
      "format": "binary",
      "type": "string"
    }
  }
}

Responses

Field definitions: AssetUploadResultDto

{
  "104": {
    "description": "Committed private upload resource exists; Location identifies resumable state"
  },
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetUploadResultDto"
        }
      }
    },
    "description": ""
  },
  "201": {
    "description": "Private upload resource created, incomplete bytes are never an asset"
  },
  "202": {
    "description": "Complete bytes verified; ingestion remains pending"
  }
}

Commit two verified Live Photo upload resources atomically

POST /api/assets/uploads/live-photo/commit

Authentication: API key. Permission: asset.upload.

Request body

Required.

Field definitions: LivePhotoUploadCommitDto

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

Responses

Field definitions: LivePhotoUploadResultDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/LivePhotoUploadResultDto"
        }
      }
    },
    "description": ""
  },
  "202": {
    "description": "Both assets committed atomically; required ingestion remains pending"
  },
  "409": {
    "description": "Incompatible pair, existing unrelated duplicate, or concurrent request"
  }
}

Cancel an unpublished upload

DELETE /api/assets/uploads/{id}

Authentication: API key. Permission: asset.upload.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

{
  "204": {
    "description": "Upload cancelled"
  }
}

Get durable upload offset

HEAD /api/assets/uploads/{id}

Authentication: API key. Permission: asset.upload.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

{
  "204": {
    "description": "Durable acknowledged offset; completion only after final processing",
    "headers": {
      "Upload-Complete": {
        "schema": {
          "enum": [
            "?0",
            "?1"
          ],
          "type": "string"
        }
      },
      "Upload-Offset": {
        "schema": {
          "minimum": 0,
          "type": "integer"
        }
      }
    }
  }
}

Append immutable upload bytes

PATCH /api/assets/uploads/{id}

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
Upload-Complete	header	Yes	string
Upload-Draft-Interop-Version	header	Yes	string
Upload-Offset	header	Yes	integer
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "Upload-Complete",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "enum": [
        "?0",
        "?1"
      ]
    }
  },
  {
    "name": "Upload-Draft-Interop-Version",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "enum": [
        "9"
      ]
    }
  },
  {
    "name": "Upload-Offset",
    "in": "header",
    "required": true,
    "schema": {
      "type": "integer",
      "minimum": 0
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

{
  "application/partial-upload": {
    "schema": {
      "format": "binary",
      "type": "string"
    }
  }
}

Responses

Field definitions: AssetUploadResultDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetUploadResultDto"
        }
      }
    },
    "description": ""
  },
  "202": {
    "description": "Same upload is pending final ingestion; retry empty completion at the durable offset"
  },
  "204": {
    "description": "Immutable append durably acknowledged",
    "headers": {
      "Upload-Complete": {
        "schema": {
          "enum": [
            "?0",
            "?1"
          ],
          "type": "string"
        }
      },
      "Upload-Offset": {
        "schema": {
          "minimum": 0,
          "type": "integer"
        }
      }
    }
  },
  "409": {
    "description": "Offset or state conflict; HEAD returns the durable acknowledged offset"
  }
}

Recover a completed upload result

GET /api/assets/uploads/{id}/result

Authentication: API key. Permission: asset.upload.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetUploadResultDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetUploadResultDto"
        }
      }
    },
    "description": ""
  },
  "202": {
    "description": "Ingestion pending; retry this same resource"
  }
}

Retrieve an asset

GET /api/assets/{id}

Retrieve detailed information about a specific asset.

Authentication: API key. Permission: asset.read.

Parameters

Name	Where	Required	Description
id	path	Yes	string
key	query	No	string
slug	query	No	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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetResponseDto

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

Update an asset

PUT /api/assets/{id}

Update information of a specific asset.

Deprecated. Avoid this operation in new integrations; use the replacement supported by your server release.

Authentication: API key. Permission: asset.update.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: UpdateAssetDto

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

Responses

Field definitions: AssetResponseDto

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

List develop versions of an asset

GET /api/assets/{id}/develop

Every saved still-image edit recipe for the asset, newest first, with its render state and which one is current.

Authentication: API key. Permission: asset.edit.get.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetDevelopResponseDto

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

Save a develop recipe as a new version

PUT /api/assets/{id}/develop

Stores the recipe as the next revision of the asset and, by default, queues the edited master render. The original file is never changed.

Authentication: API key. Permission: asset.edit.create.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetDevelopSaveDto

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

Responses

Field definitions: AssetDevelopRevisionResponseDto

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

Upload a develop artifact

POST /api/assets/{id}/develop/artifacts

keeps a subject, sky or background mask bitmap (greyscale, covering the whole original) or a Clean Up fill (RGBA, covering its area) that a client computed for this photo. Recipes reference it by the returned id, the SHA-256 of the stored PNG, so every client and the server render the same result. Uploading the same bitmap again returns the same id. A recipe that references an artifact this photo does not have is refused with `develop_artifact_missing`.

Authentication: API key. Permission: asset.edit.create.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required. A mask bitmap or a generated fill for this photo

Field definitions: AssetDevelopArtifactUploadDto

{
  "multipart/form-data": {
    "schema": {
      "$ref": "#/components/schemas/AssetDevelopArtifactUploadDto"
    }
  }
}

Responses

Field definitions: AssetDevelopArtifactResponseDto

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

List exports of an original for editing elsewhere

GET /api/assets/{id}/develop/exports

Every recorded export of the original, newest first, and whether the original still matches it.

Authentication: API key. Permission: asset.edit.get.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: DevelopExportResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/DevelopExportResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Export an original for editing elsewhere

POST /api/assets/{id}/develop/exports

Records the SHA-256 of the original now, so a file developed from it in another application can be brought back and checked. Download the original through the ordinary download route.

Authentication: API key. Permission: asset.edit.create.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: DevelopExportResponseDto

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

Bring back a file developed elsewhere

POST /api/assets/{id}/develop/imports

Checks that the file arrived intact and was developed from the original the photo has now, then keeps it as a new version and renders its preview. Nothing is kept when a check fails; the original is never changed.

Authentication: API key. Permission: asset.edit.create.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required. The developed file and the original it was made from

Field definitions: AssetDevelopImportDto

{
  "multipart/form-data": {
    "schema": {
      "$ref": "#/components/schemas/AssetDevelopImportDto"
    }
  }
}

Responses

Field definitions: AssetDevelopRevisionResponseDto

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

Suggest a subject or sky mask locally

POST /api/assets/{id}/develop/masks/propose

Authentication: API key. Permission: asset.edit.create.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetDevelopSemanticMaskDto

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

Responses

Field definitions: AssetDevelopArtifactResponseDto

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

Render a develop preview

POST /api/assets/{id}/develop/preview

Renders the recipe from the original at preview size and returns the image; nothing is stored.

Authentication: API key. Permission: asset.edit.get.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetDevelopPreviewDto

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

Responses

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

Revert to the original or an earlier develop version

POST /api/assets/{id}/develop/revert

Makes the named rendered version current, or the original when no version is named. History and files are kept.

Authentication: API key. Permission: asset.edit.create.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetDevelopRevertDto

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

Responses

Field definitions: AssetDevelopResponseDto

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

View a rendered develop file

GET /api/assets/{id}/develop/revisions/{revisionId}/file

Streams the edited master or the preview rendered for the version.

Authentication: API key. Permission: asset.edit.get.

Parameters

Name	Where	Required	Description
id	path	Yes	Asset ID
kind	query	No
revisionId	path	Yes	Develop revision ID

Parameter types, defaults and constraints

Field definitions: AssetDevelopFileKind

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "description": "Asset ID",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "kind",
    "required": false,
    "in": "query",
    "schema": {
      "default": "preview",
      "$ref": "#/components/schemas/AssetDevelopFileKind"
    }
  },
  {
    "name": "revisionId",
    "required": true,
    "in": "path",
    "description": "Develop revision ID",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[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": ""
  }
}

Cancel a develop render

DELETE /api/assets/{id}/develop/revisions/{revisionId}/render

Stops a queued or running render of the version. Files already rendered for other versions are untouched.

Authentication: API key. Permission: asset.edit.create.

Parameters

Name	Where	Required	Description
id	path	Yes	Asset ID
revisionId	path	Yes	Develop revision ID

Parameter types, defaults and constraints

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

Responses

Field definitions: AssetDevelopRevisionResponseDto

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

Render a develop version

POST /api/assets/{id}/develop/revisions/{revisionId}/render

Queues (or re-queues after a failure or cancellation) the edited master render of a saved version.

Authentication: API key. Permission: asset.edit.create.

Parameters

Name	Where	Required	Description
id	path	Yes	Asset ID
revisionId	path	Yes	Develop revision ID

Parameter types, defaults and constraints

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

Responses

Field definitions: AssetDevelopRevisionResponseDto

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

List saved video versions

GET /api/assets/{id}/edit-versions

Authentication: API key. Permission: asset.edit.get.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: VideoEditVersionResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/VideoEditVersionResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Export the current video version

POST /api/assets/{id}/edit-versions/export

Authentication: API key. Permission: asset.edit.create.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: VideoEditExportDto

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

Responses

Field definitions: VideoEditVersionResponseDto

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

Prune an unselected video version

DELETE /api/assets/{id}/edit-versions/{versionId}

Authentication: API key. Permission: asset.edit.delete.

Parameters

Name	Where	Required	Description
id	path	Yes	string
versionId	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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "versionId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Responses

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

Download a video version master

GET /api/assets/{id}/edit-versions/{versionId}/download

Authentication: API key. Permission: asset.download.

Parameters

Name	Where	Required	Description
id	path	Yes	string
versionId	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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "versionId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Responses

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

Restore a saved video version

POST /api/assets/{id}/edit-versions/{versionId}/restore

Authentication: API key. Permission: asset.edit.create.

Parameters

Name	Where	Required	Description
id	path	Yes	string
versionId	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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "versionId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Responses

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

Remove edits from an existing asset

DELETE /api/assets/{id}/edits

Removes all edit actions (crop, rotate, mirror) associated with the specified asset.

Authentication: API key. Permission: asset.edit.delete.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

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

Retrieve edits for an existing asset

GET /api/assets/{id}/edits

Retrieve a series of edit actions (crop, rotate, mirror) associated with the specified asset.

Authentication: API key. Permission: asset.edit.get.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetEditsResponseDto

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

Apply edits to an existing asset

PUT /api/assets/{id}/edits

Apply a series of edit actions (crop, rotate, mirror) to the specified asset.

Authentication: API key. Permission: asset.edit.create.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetEditsCreateDto

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

Responses

Field definitions: AssetEditsResponseDto

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

List the original video's keyframes

GET /api/assets/{id}/edits/keyframes

The keyframe times of the original video, so an editor can show where a fast (keyframe) trim actually cuts. Owner's edit permission only; never the edited version.

Authentication: API key. Permission: asset.edit.get.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetEditKeyframesResponseDto

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

Get image enrichment metadata

GET /api/assets/{id}/image-enrichment

Retrieve private image description, tag, and NSFW detection metadata for a specific asset.

Authentication: API key. Permission: asset.update.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetImageEnrichmentResponseDto

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

Update image enrichment metadata

PUT /api/assets/{id}/image-enrichment

Run repair actions for generated image descriptions, tags, and NSFW detection metadata.

Authentication: API key. Permission: asset.update.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetImageEnrichmentActionRequestDto

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

Responses

Field definitions: AssetImageEnrichmentResponseDto

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

Get asset metadata

GET /api/assets/{id}/metadata

Retrieve all metadata key-value pairs associated with the specified asset.

Authentication: API key. Permission: asset.read.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetMetadataResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/AssetMetadataResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Update asset metadata

PUT /api/assets/{id}/metadata

Update or add metadata key-value pairs for the specified asset.

Authentication: API key. Permission: asset.update.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetMetadataUpsertDto

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

Responses

Field definitions: AssetMetadataResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/AssetMetadataResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Delete asset metadata by key

DELETE /api/assets/{id}/metadata/{key}

Delete a specific metadata key-value pair associated with the specified asset.

Authentication: API key. Permission: asset.update.

Parameters

Name	Where	Required	Description
id	path	Yes	Asset ID
key	path	Yes	Metadata key

Parameter types, defaults and constraints

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

Responses

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

Retrieve asset metadata by key

GET /api/assets/{id}/metadata/{key}

Retrieve the value of a specific metadata key associated with the specified asset.

Authentication: API key. Permission: asset.read.

Parameters

Name	Where	Required	Description
id	path	Yes	Asset ID
key	path	Yes	Metadata key

Parameter types, defaults and constraints

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

Responses

Field definitions: AssetMetadataResponseDto

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

Retrieve asset OCR data

GET /api/assets/{id}/ocr

Retrieve all OCR (Optical Character Recognition) data associated with the specified asset.

Authentication: API key. Permission: asset.read.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetOcrResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/AssetOcrResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Download original asset

GET /api/assets/{id}/original

Downloads the original file of the specified asset.

Authentication: API key. Permission: asset.download.

Parameters

Name	Where	Required	Description
edited	query	No	Return edited asset if available
id	path	Yes	string
key	query	No	string
slug	query	No	string

Parameter types, defaults and constraints

[
  {
    "name": "edited",
    "required": false,
    "in": "query",
    "description": "Return edited asset if available",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
]

Responses

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

Discard a restoration

DELETE /api/assets/{id}/restorations/{restorationId}

Cancels anything still running, stops using the result for playback and removes every file the restoration produced. The record stays as history.

Authentication: API key. Permission: asset.edit.create.

Parameters

Name	Where	Required	Description
id	path	Yes	Asset ID
restorationId	path	Yes	Restoration ID

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "description": "Asset ID",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "restorationId",
    "required": true,
    "in": "path",
    "description": "Restoration ID",
    "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": ""
  }
}

View a restoration file

GET /api/assets/{id}/restorations/{restorationId}/file

Streams the preview input, the restored preview, the full result or its playback rendition.

Authentication: API key. Permission: asset.edit.get.

Parameters

Name	Where	Required	Description
id	path	Yes	Asset ID
kind	query	No
restorationId	path	Yes	Restoration ID

Parameter types, defaults and constraints

Field definitions: AssetRestorationFileKind

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "description": "Asset ID",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "kind",
    "required": false,
    "in": "query",
    "schema": {
      "default": "after",
      "$ref": "#/components/schemas/AssetRestorationFileKind"
    }
  },
  {
    "name": "restorationId",
    "required": true,
    "in": "path",
    "description": "Restoration ID",
    "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": ""
  }
}

View asset thumbnail

GET /api/assets/{id}/thumbnail

Retrieve the thumbnail image for the specified asset. Viewing the fullsize thumbnail might redirect to downloadAsset, which requires a different permission.

Authentication: API key. Permission: asset.view.

Parameters

Name	Where	Required	Description
edited	query	No	Return edited asset if available
faceSource	query	No	Return the ordinary edited preview used for face coordinates
id	path	Yes	string
key	query	No	string
size	query	No
slug	query	No	string

Parameter types, defaults and constraints

Field definitions: AssetMediaSize

[
  {
    "name": "edited",
    "required": false,
    "in": "query",
    "description": "Return edited asset if available",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "faceSource",
    "required": false,
    "in": "query",
    "description": "Return the ordinary edited preview used for face coordinates",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "size",
    "required": false,
    "in": "query",
    "schema": {
      "$ref": "#/components/schemas/AssetMediaSize"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
]

Responses

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

Play asset video

GET /api/assets/{id}/video/playback

Streams the video file for the specified asset. This endpoint also supports byte range requests.

Authentication: API key. Permission: asset.view.

Parameters

Name	Where	Required	Description
edited	query	No	Play the edited version when one exists (default). false plays the unedited source for the asset's owner, as the quick editor needs; everyone else is always given the edited version
id	path	Yes	string
key	query	No	string
slug	query	No	string

Parameter types, defaults and constraints

[
  {
    "name": "edited",
    "required": false,
    "in": "query",
    "description": "Play the edited version when one exists (default). false plays the unedited source for the asset's owner, as the quick editor needs; everyone else is always given the edited version",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
]

Responses

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

Get HLS main playlist

GET /api/assets/{id}/video/stream/main.m3u8

Returns an HLS main playlist with all available variants for the asset.

Authentication: API key. Permission: asset.view.

Parameters

Name	Where	Required	Description
id	path	Yes	string
key	query	No	string
slug	query	No	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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
]

Responses

{
  "200": {
    "content": {
      "application/vnd.apple.mpegurl": {
        "schema": {
          "type": "string"
        }
      }
    },
    "description": ""
  }
}

End HLS streaming session

DELETE /api/assets/{id}/video/stream/{sessionId}

Releases server resources for the streaming session.

Authentication: API key. Permission: asset.view.

Parameters

Name	Where	Required	Description
id	path	Yes	string
key	query	No	string
sessionId	path	Yes	string
slug	query	No	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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "sessionId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
]

Responses

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

Get HLS media playlist

GET /api/assets/{id}/video/stream/{sessionId}/{variantIndex}/playlist.m3u8

Returns an HLS media playlist for one variant of the streaming session.

Authentication: API key. Permission: asset.view.

Parameters

Name	Where	Required	Description
id	path	Yes	string
key	query	No	string
sessionId	path	Yes	string
slug	query	No	string
variantIndex	path	Yes	integer
x-immich-hls-pos	header	No	number

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "sessionId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "variantIndex",
    "required": true,
    "in": "path",
    "schema": {
      "minimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    }
  },
  {
    "name": "x-immich-hls-pos",
    "required": false,
    "in": "header",
    "schema": {
      "minimum": 0,
      "type": "number"
    }
  }
]

Responses

{
  "200": {
    "content": {
      "application/vnd.apple.mpegurl": {
        "schema": {
          "type": "string"
        }
      }
    },
    "description": ""
  }
}

Get HLS segment or init file

GET /api/assets/{id}/video/stream/{sessionId}/{variantIndex}/{filename}

Streams an HLS init segment (init.mp4) or media segment (seg_N.m4s).

Authentication: API key. Permission: asset.view.

Parameters

Name	Where	Required	Description
filename	path	Yes	string
id	path	Yes	string
key	query	No	string
sessionId	path	Yes	string
slug	query	No	string
variantIndex	path	Yes	integer
x-immich-hls-msn	header	No	integer

Parameter types, defaults and constraints

[
  {
    "name": "filename",
    "required": true,
    "in": "path",
    "schema": {
      "pattern": "^(init\\.mp4|seg_\\d+\\.m4s)$",
      "type": "string"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "key",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "sessionId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "slug",
    "required": false,
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "variantIndex",
    "required": true,
    "in": "path",
    "schema": {
      "minimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    }
  },
  {
    "name": "x-immich-hls-msn",
    "required": false,
    "in": "header",
    "schema": {
      "minimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    }
  }
]

Responses

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

Play the Studio HDR intermediate

GET /api/assets/{id}/video/studio-hdr

streams the 10-bit AV1 intermediate that keeps an HDR video’s BT.2020 PQ or HLG signal, for the Studio editor. Not found until it has been made (placing the video in a Studio project queues it). Supports byte range requests.

Authentication: API key. Permission: asset.view.

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}-4[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": ""
  }
}

List develop presets

GET /api/develop-presets

Your saved develop presets, by name.

Authentication: API key. Permission: all.

Responses

Field definitions: DevelopPresetResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/DevelopPresetResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Save a develop preset

POST /api/develop-presets

Saves develop settings (sliders, look, strength and masks, never geometry) under a new name.

Authentication: API key. Permission: all.

Request body

Required.

Field definitions: DevelopPresetCreateDto

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

Responses

Field definitions: DevelopPresetResponseDto

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

Delete a develop preset

DELETE /api/develop-presets/{id}

Deletes the preset. Versions already saved with its settings are unchanged.

Authentication: API key. Permission: all.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

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

Update a develop preset

PUT /api/develop-presets/{id}

Renames a preset, changes its settings, or both. Settings the request leaves out keep their stored values.

Authentication: API key. Permission: all.

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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: DevelopPresetUpdateDto

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

Responses

Field definitions: DevelopPresetResponseDto

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

List Google Photos imports

GET /api/takeout

Authentication: API key. Permission: asset.upload.

Responses

Field definitions: TakeoutResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/TakeoutResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Start a Google Photos import

POST /api/takeout

Creates an import to stage Takeout archives into. Administrators may instead name a folder inside one of the permitted import locations.

Authentication: API key. Permission: asset.upload.

Request body

Required.

Field definitions: TakeoutCreateDto

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

Responses

Field definitions: TakeoutResponseDto

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

List the permitted import locations

GET /api/takeout/roots

Administrator access required.

Authentication: API key. Permission: all.

Responses

Field definitions: TakeoutRootsResponseDto

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

Delete a Google Photos import

DELETE /api/takeout/{id}

Removes the import and its staged copies. Everything it brought into the library stays there.

Authentication: API key. Permission: asset.upload.

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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Responses

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

Get a Google Photos import

GET /api/takeout/{id}

Authentication: API key. Permission: asset.upload.

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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Responses

Field definitions: TakeoutResponseDto

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

Stage a Takeout archive

POST /api/takeout/{id}/archives

Authentication: API key. Permission: asset.upload.

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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: TakeoutArchiveCreateDto

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

Responses

Field definitions: TakeoutSourceResponseDto

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

Remove a staged Takeout archive

DELETE /api/takeout/{id}/archives/{archiveId}

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
archiveId	path	Yes	string
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "archiveId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Responses

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

Upload part of a Takeout archive

PUT /api/takeout/{id}/archives/{archiveId}/chunks

Appends up to 8 MiB at the given byte offset. Repeating a part already staged is harmless.

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
archiveId	path	Yes	string
id	path	Yes	string
offset	query	Yes	Byte offset of this chunk

Parameter types, defaults and constraints

[
  {
    "name": "archiveId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "offset",
    "required": true,
    "in": "query",
    "description": "Byte offset of this chunk",
    "schema": {
      "minimum": 0,
      "maximum": 1099511627776,
      "type": "integer"
    }
  }
]

Request body

Required.

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

Responses

Field definitions: TakeoutSourceResponseDto

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

Check a staged part of a Takeout archive

POST /api/takeout/{id}/archives/{archiveId}/verify

Compares a range already uploaded with the file the browser is about to resume from.

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
archiveId	path	Yes	string
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "archiveId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: TakeoutVerifyChunkDto

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

Responses

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

Pause, resume or cancel a Google Photos import

POST /api/takeout/{id}/control

Authentication: API key. Permission: asset.upload.

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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: TakeoutControlDto

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

Responses

Field definitions: TakeoutResponseDto

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

Import the reviewed items

POST /api/takeout/{id}/import

Queues the import as a background job with these choices. Items already in the library are matched, not copied again, and keep their album memberships.

Authentication: API key. Permission: asset.upload.

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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: TakeoutOptionsDto

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

Responses

Field definitions: TakeoutResponseDto

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

List the items of a Google Photos import

GET /api/takeout/{id}/items

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
id	path	Yes	string
limit	query	No	Items to return
offset	query	No	Items to skip
state	query	No

Parameter types, defaults and constraints

Field definitions: TakeoutItemState

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "limit",
    "required": false,
    "in": "query",
    "description": "Items to return",
    "schema": {
      "minimum": 1,
      "maximum": 200,
      "default": 100,
      "type": "integer"
    }
  },
  {
    "name": "offset",
    "required": false,
    "in": "query",
    "description": "Items to skip",
    "schema": {
      "minimum": 0,
      "maximum": 9007199254740991,
      "default": 0,
      "type": "integer"
    }
  },
  {
    "name": "state",
    "required": false,
    "in": "query",
    "schema": {
      "$ref": "#/components/schemas/TakeoutItemState"
    }
  }
]

Responses

Field definitions: TakeoutItemsResponseDto

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

Choose metadata for an item, or leave it out

PUT /api/takeout/{id}/items/{itemId}

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
id	path	Yes	string
itemId	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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "itemId",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: TakeoutResolveDto

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

Responses

Field definitions: TakeoutResponseDto

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

List possible Live Photos in a Google Photos import

GET /api/takeout/{id}/live-photos

Authentication: API key. Permission: asset.upload.

Parameters

Name	Where	Required	Description
id	path	Yes	string
limit	query	No	Pairs to return
offset	query	No	Pairs to skip
state	query	No

Parameter types, defaults and constraints

Field definitions: TakeoutPairState

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  },
  {
    "name": "limit",
    "required": false,
    "in": "query",
    "description": "Pairs to return",
    "schema": {
      "minimum": 1,
      "maximum": 200,
      "default": 100,
      "type": "integer"
    }
  },
  {
    "name": "offset",
    "required": false,
    "in": "query",
    "description": "Pairs to skip",
    "schema": {
      "minimum": 0,
      "maximum": 9007199254740991,
      "default": 0,
      "type": "integer"
    }
  },
  {
    "name": "state",
    "required": false,
    "in": "query",
    "schema": {
      "$ref": "#/components/schemas/TakeoutPairState"
    }
  }
]

Responses

Field definitions: TakeoutPairsResponseDto

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

Link or separate a possible Live Photo

PUT /api/takeout/{id}/live-photos

Authentication: API key. Permission: asset.upload.

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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: TakeoutPairDecisionDto

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

Responses

Field definitions: TakeoutPairsResponseDto

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

Scan a Google Photos import

POST /api/takeout/{id}/scan

Queues the scan of the staged sources as a background job that continues after the browser closes.

Authentication: API key. Permission: asset.upload.

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}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "type": "string"
    }
  }
]

Responses

Field definitions: TakeoutResponseDto

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