Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API
An asset is a photo or video in your library, identified by a single asset ID.
A version is a stored file belonging to that asset. Saving an edited photo
as a version keeps the asset’s ID, album memberships, metadata, and face and
person associations.
Original and derived versions
There are two categories of asset versions:
Original version: the file you first uploaded, preserved unchanged. Its
kind is original.
Derived version: a new file produced by editing or processing the photo.
It contains the finished image and parameters describing how it was produced.
Its kind identifies the producer: edit for a client-rendered edit, or
external:<service> for an external producer.
The current version is the one Gumnut shows when you browse the asset or
request its image URLs. Before you save an edit, the original is current.
After you save an edit, the derived version is current, and the original remains
available to download or restore. Either an original or a derived version can
be current.Gumnut keeps the original and at most one derived version per asset. Your first
edit adds a derived version; saving another edit replaces that derived version
with a new one. For example, if you crop a photo and later change the crop,
Gumnut keeps the untouched upload and the latest cropped image.Each retained version has its own version ID and a position. Position 0 is
the original, and the highest retained position is current. Version IDs identify
specific stored files; positions can be reused after deletion or revert.
Replacing a derived version or reverting to the original permanently removes
the current derived version.
There is no undo history of earlier saved edits. Download a version first if
you need to keep it separately.
How editing works
The Photos API stores finished image files as derived versions. Your
application applies the crop, rotation, filter, or external editing operation
and uploads the resulting image. Sending a recipe alone does not cause the
Photos API to render it.
Prerequisites
Before starting, you need:
An API key scoped to the photo’s library.
Reading versions requires read; adding or replacing versions requires
write; deleting or reverting versions requires delete_permanently.
The photo’s asset ID and a fully rendered JPEG or PNG, with orientation and
all edits already applied to its pixels. The file limit is 100 MiB, including
any metadata the API adds during finalization.
curl to run the examples below. Set GUMNUT_API_KEY to your key and
ASSET_ID to an existing asset ID.
The response is an array ordered by position: position 0 is the original
upload, and the last entry is current. Each entry has an id, kind, params,
and file details such as dimensions and size. include=variants adds URLs
beyond the default thumbnail, including version_urls.original.url for that
version’s exact stored bytes.Normal asset responses and asset_urls describe the current version.
Even asset_urls.original refers to the current version’s stored file. To
retrieve the untouched upload after an edit, use the position-0 version’s
version_urls.original.url instead.
Add or replace a derived version
When the original is current, upload your edited image to add a derived version.
This example assumes edited.jpg already contains the original rotated
90 degrees clockwise:
The multipart fields are file, kind, and params. params is a JSON object
serialized as a string; the API stores it without interpreting its editing
instructions. Use kind=edit with the compatible recipe below for geometric
edits, or external:<service> with your producer’s own parameters for other
derived versions. original is reserved for the uploaded source.For interoperability with Gumnut and Immich editors, the version-1 recipe has:
version: 1.
angle: 0, 90, 180, or 270 degrees clockwise.
mirror: a boolean for a horizontal flip after rotation.
Optional crop: integer x, y, width, and height in the base image’s
display-oriented pixels, before rotation. Keep the rectangle within the image
and use positive width and height. Omit crop when there is no crop.
Render in the order crop → rotate → horizontal mirror. A vertical flip is
represented by a 180-degree rotation combined with a horizontal mirror.
The finished image must match the recipe; the API does not check that match.
The built-in editors refuse unfamiliar recipe fields rather than discard them
on the next save.A version produced by an external service remains viewable and downloadable,
but the built-in editors cannot reopen it as an adjustable geometric edit.
Restore the original
Set ORIGINAL_VERSION_ID to the id of the position-0 version, then revert:
Revert makes the addressed retained version current and permanently removes
its descendants. Alternatively, DELETE /api/assets/{asset_id}/versions/{version_id} removes the current non-original
version and restores its predecessor. You cannot delete the original through
that endpoint.
Handle saves and conflicts
A new append or replacement returns 201. An exact retry with the same
kind, parameters, and finalized bytes returns the current version with 200
and stores nothing new.
A stale append or replacement returns 409. Refetch the asset and versions
before deciding whether to replace the latest edit; do not blindly overwrite
someone else’s changes. The SDKs don’t retry this conflict automatically.
422 means the body, metadata, or image is invalid. 507 means retaining
the version would exceed storage capacity. Every retained version, including
the original, counts toward storage use.
The API copies metadata from the original during finalization, so stored
bytes can differ from your upload. Use the returned version’s checksum and
URLs when tracking the saved result.
See the API Reference tab for endpoint schemas and error responses.
Faces on edited photos
Face boxes are anchored to the original photo’s pixel coordinates. While a
derived version is current, Gumnut and the Immich adapter hide those boxes
and reject new manual boxes rather than draw or save them in the wrong place.
Your existing face and person associations remain attached to the asset.
Restoring the original makes its face geometry available again.
{"docsConfig":{"theme":"palm","$schema":"https://mintlify.com/docs.json","name":"Gumnut AI","description":"Gumnut is an AI-powered, open alternative to Google and Apple Photos — and an open platform for building on your library through a REST API, native SDKs, a hosted MCP server, and Immich compatibility.","colors":{"primary":"#5A4CD6","light":"#8E80F0","dark":"#5A4CD6"},"logo":{"light":"https://mintcdn.com/gumnutai/g7uvIAJIK6-HCQWp/logo/gumnut-logotype-horizontal-light.svg?fit=max\u0026auto=format\u0026n=g7uvIAJIK6-HCQWp\u0026q=85\u0026s=2a6ec085314f83e9fb98e806c60a6667","dark":"https://mintcdn.com/gumnutai/g7uvIAJIK6-HCQWp/logo/gumnut-logotype-horizontal-dark.svg?fit=max\u0026auto=format\u0026n=g7uvIAJIK6-HCQWp\u0026q=85\u0026s=a067b12c8fb73332dc59ffbc25ef7074"},"favicon":"https://mintcdn.com/gumnutai/Hs-Y3ah5ynxxRsxf/favicon.ico?fit=max\u0026auto=format\u0026n=Hs-Y3ah5ynxxRsxf\u0026q=85\u0026s=56f919e27dd1e3fa1b120b9c062d919f","background":{"color":{"light":"#FFFFFF","dark":"#171717"}},"navbar":{"primary":{"type":"button","label":"Dashboard","href":"https://app.gumnut.ai"}},"footer":{"links":[{"header":"Product","items":[{"label":"Home","href":"https://www.gumnut.ai"},{"label":"Features","href":"https://www.gumnut.ai"},{"label":"Developers","href":"https://www.gumnut.ai"},{"label":"FAQ","href":"https://www.gumnut.ai"}]},{"header":"Developers","items":[{"label":"Getting Started","href":"/guides/getting-started/introduction"},{"label":"API Docs","href":"/api-reference"},{"label":"SDK Docs","href":"/guides/sdks/overview"},{"label":"MCP Docs","href":"/guides/mcp/overview"}]},{"header":"Company","items":[{"label":"About","href":"https://www.gumnut.ai/about"},{"label":"Blog","href":"https://blog.gumnut.ai/"},{"label":"Support","href":"https://www.gumnut.ai/contact"},{"label":"Privacy Policy","href":"https://www.gumnut.ai/privacy"}]}]},"fonts":{"family":"Inter"},"icons":{"library":"lucide"},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Gumnut Home","icon":"house","href":"https://www.gumnut.ai"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"gumnutai","hasAudioNarration":false,"actualSubdomain":"gumnutai","customDomains":["docs.gumnut.ai"],"gitSource":{"type":"github","owner":"gumnut-ai","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"agentFeedback":true},"entitlements":{},"buildId":"6b008c0296cb7b3855785a6f","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"API reference","count":85},{"language":"default","tag":"Guides","count":36},{"language":"default","tag":"assets","count":19},{"language":"default","tag":"libraries","count":11},{"language":"default","tag":"Product features","count":10},{"language":"default","tag":"APIs","count":9},{"language":"default","tag":"albums","count":7},{"language":"default","tag":"people","count":7},{"language":"default","tag":"stacks","count":7},{"language":"default","tag":"library-invitations","count":6}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"guides/apis/asset-versioning","slug":"/guides/apis/asset-versioning","pageMetadata":{"title":"Versioning and editing assets","description":"Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API","href":"/guides/apis/asset-versioning"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`An asset is a photo or video in your library, identified by a single asset ID.\nA `,_jsx(_components.strong,{children:`version`}),` is a stored file belonging to that asset. Saving an edited photo\nas a version keeps the asset’s ID, album memberships, metadata, and face and\nperson associations.`]}),`\n`,_jsx(Heading,{level:`2`,id:`original-and-derived-versions`,children:`Original and derived versions`}),`\n`,_jsx(_components.p,{children:`There are two categories of asset versions:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Original version`}),`: the file you first uploaded, preserved unchanged. Its\n`,_jsx(_components.code,{children:`kind`}),` is `,_jsx(_components.code,{children:`original`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Derived version`}),`: a new file produced by editing or processing the photo.\nIt contains the finished image and parameters describing how it was produced.\nIts `,_jsx(_components.code,{children:`kind`}),` identifies the producer: `,_jsx(_components.code,{children:`edit`}),` for a client-rendered edit, or\n`,_jsx(_components.code,{children:`external:\u003cservice>`}),` for an external producer.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`The `,_jsx(_components.strong,{children:`current version`}),` is the one Gumnut shows when you browse the asset or\nrequest its image URLs. Before you save an edit, the original is current.\nAfter you save an edit, the derived version is current, and the original remains\navailable to download or restore. Either an original or a derived version can\nbe current.`]}),`\n`,_jsx(_components.p,{children:`Gumnut keeps the original and at most one derived version per asset. Your first\nedit adds a derived version; saving another edit replaces that derived version\nwith a new one. For example, if you crop a photo and later change the crop,\nGumnut keeps the untouched upload and the latest cropped image.`}),`\n`,_jsxs(_components.p,{children:[`Each retained version has its own version ID and a `,_jsx(_components.code,{children:`position`}),`. Position `,_jsx(_components.code,{children:`0`}),` is\nthe original, and the highest retained position is current. Version IDs identify\nspecific stored files; positions can be reused after deletion or revert.`]}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`Replacing a derived version or reverting to the original permanently removes\nthe current derived version.\nThere is no undo history of earlier saved edits. Download a version first if\nyou need to keep it separately.`})}),`\n`,_jsx(Heading,{level:`2`,id:`how-editing-works`,children:`How editing works`}),`\n`,_jsxs(_components.p,{children:[`The Photos API stores `,_jsx(_components.strong,{children:`finished image files`}),` as derived versions. Your\napplication applies the crop, rotation, filter, or external editing operation\nand uploads the resulting image. Sending a recipe alone does not cause the\nPhotos API to render it.`]}),`\n`,_jsx(Heading,{level:`2`,id:`prerequisites`,children:`Prerequisites`}),`\n`,_jsx(_components.p,{children:`Before starting, you need:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`An `,_jsx(_components.a,{href:`/guides/authentication/api-keys`,children:`API key`}),` scoped to the photo’s library.\nReading versions requires `,_jsx(_components.code,{children:`read`}),`; adding or replacing versions requires\n`,_jsx(_components.code,{children:`write`}),`; deleting or reverting versions requires `,_jsx(_components.code,{children:`delete_permanently`}),`.`]}),`\n`,_jsx(_components.li,{children:`The photo’s asset ID and a fully rendered JPEG or PNG, with orientation and\nall edits already applied to its pixels. The file limit is 100 MiB, including\nany metadata the API adds during finalization.`}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`curl`}),` to run the examples below. Set `,_jsx(_components.code,{children:`GUMNUT_API_KEY`}),` to your key and\n`,_jsx(_components.code,{children:`ASSET_ID`}),` to an existing asset ID.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`read-the-retained-versions`,children:`Read the retained versions`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --fail-with-body`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"https://api.gumnut.ai/api/assets/${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ASSET_ID`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/versions?include=variants\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"Authorization: Bearer ${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`GUMNUT_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The response is an array ordered by `,_jsx(_components.code,{children:`position`}),`: position `,_jsx(_components.code,{children:`0`}),` is the original\nupload, and the last entry is current. Each entry has an `,_jsx(_components.code,{children:`id`}),`, `,_jsx(_components.code,{children:`kind`}),`, `,_jsx(_components.code,{children:`params`}),`,\nand file details such as dimensions and size. `,_jsx(_components.code,{children:`include=variants`}),` adds URLs\nbeyond the default thumbnail, including `,_jsx(_components.code,{children:`version_urls.original.url`}),` for that\nversion’s exact stored bytes.`]}),`\n`,_jsxs(_components.p,{children:[`Normal asset responses and `,_jsx(_components.code,{children:`asset_urls`}),` describe the `,_jsx(_components.strong,{children:`current version`}),`.\nEven `,_jsx(_components.code,{children:`asset_urls.original`}),` refers to the current version’s stored file. To\nretrieve the untouched upload after an edit, use the position-0 version’s\n`,_jsx(_components.code,{children:`version_urls.original.url`}),` instead.`]}),`\n`,_jsx(Heading,{level:`2`,id:`add-or-replace-a-derived-version`,children:`Add or replace a derived version`}),`\n`,_jsxs(_components.p,{children:[`When the original is current, upload your edited image to add a derived version.\nThis example assumes `,_jsx(_components.code,{children:`edited.jpg`}),` already contains the original rotated\n90 degrees clockwise:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`6`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --fail-with-body`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` POST`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"https://api.gumnut.ai/api/assets/${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ASSET_ID`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/versions?include=variants\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"Authorization: Bearer ${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`GUMNUT_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -F`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'file=@edited.jpg;type=image/jpeg'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -F`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'kind=edit'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -F`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'params={\"version\":1,\"angle\":90,\"mirror\":false}'`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`When a derived version is already current, set `,_jsx(_components.code,{children:`CURRENT_VERSION_ID`}),` to its `,_jsx(_components.code,{children:`id`}),`\nfrom the version list and replace it:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`6`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --fail-with-body`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` POST`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"https://api.gumnut.ai/api/assets/${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ASSET_ID`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"}/versions/${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`CURRENT_VERSION_ID`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/replace?include=variants\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"Authorization: Bearer ${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`GUMNUT_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -F`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'file=@edited.jpg;type=image/jpeg'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -F`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'kind=edit'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -F`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 'params={\"version\":1,\"angle\":90,\"mirror\":false}'`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The multipart fields are `,_jsx(_components.code,{children:`file`}),`, `,_jsx(_components.code,{children:`kind`}),`, and `,_jsx(_components.code,{children:`params`}),`. `,_jsx(_components.code,{children:`params`}),` is a JSON object\nserialized as a string; the API stores it without interpreting its editing\ninstructions. Use `,_jsx(_components.code,{children:`kind=edit`}),` with the compatible recipe below for geometric\nedits, or `,_jsx(_components.code,{children:`external:\u003cservice>`}),` with your producer’s own parameters for other\nderived versions. `,_jsx(_components.code,{children:`original`}),` is reserved for the uploaded source.`]}),`\n`,_jsx(_components.p,{children:`For interoperability with Gumnut and Immich editors, the version-1 recipe has:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`version`}),`: `,_jsx(_components.code,{children:`1`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`angle`}),`: `,_jsx(_components.code,{children:`0`}),`, `,_jsx(_components.code,{children:`90`}),`, `,_jsx(_components.code,{children:`180`}),`, or `,_jsx(_components.code,{children:`270`}),` degrees clockwise.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`mirror`}),`: a boolean for a horizontal flip after rotation.`]}),`\n`,_jsxs(_components.li,{children:[`Optional `,_jsx(_components.code,{children:`crop`}),`: integer `,_jsx(_components.code,{children:`x`}),`, `,_jsx(_components.code,{children:`y`}),`, `,_jsx(_components.code,{children:`width`}),`, and `,_jsx(_components.code,{children:`height`}),` in the base image’s\ndisplay-oriented pixels, before rotation. Keep the rectangle within the image\nand use positive width and height. Omit `,_jsx(_components.code,{children:`crop`}),` when there is no crop.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`Render in the order `,_jsx(_components.strong,{children:`crop → rotate → horizontal mirror`}),`. A vertical flip is\nrepresented by a 180-degree rotation combined with a horizontal mirror.\nThe finished image must match the recipe; the API does not check that match.\nThe built-in editors refuse unfamiliar recipe fields rather than discard them\non the next save.`]}),`\n`,_jsx(_components.p,{children:`A version produced by an external service remains viewable and downloadable,\nbut the built-in editors cannot reopen it as an adjustable geometric edit.`}),`\n`,_jsx(Heading,{level:`2`,id:`restore-the-original`,children:`Restore the original`}),`\n`,_jsxs(_components.p,{children:[`Set `,_jsx(_components.code,{children:`ORIGINAL_VERSION_ID`}),` to the `,_jsx(_components.code,{children:`id`}),` of the position-0 version, then revert:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --fail-with-body`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` POST`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"https://api.gumnut.ai/api/assets/${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ASSET_ID`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:\"}/versions/${\"}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ORIGINAL_VERSION_ID`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/revert\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"Authorization: Bearer ${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`GUMNUT_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Revert makes the addressed retained version current and permanently removes\nits descendants. Alternatively, `,_jsx(_components.code,{children:`DELETE /api/assets/{asset_id}/versions/{version_id}`}),` removes the current non-original\nversion and restores its predecessor. You cannot delete the original through\nthat endpoint.`]}),`\n`,_jsx(Heading,{level:`2`,id:`handle-saves-and-conflicts`,children:`Handle saves and conflicts`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`A new append or replacement returns `,_jsx(_components.code,{children:`201`}),`. An exact retry with the same\nkind, parameters, and finalized bytes returns the current version with `,_jsx(_components.code,{children:`200`}),`\nand stores nothing new.`]}),`\n`,_jsxs(_components.li,{children:[`A stale append or replacement returns `,_jsx(_components.code,{children:`409`}),`. Refetch the asset and versions\nbefore deciding whether to replace the latest edit; do not blindly overwrite\nsomeone else’s changes. The SDKs don’t retry this conflict automatically.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`422`}),` means the body, metadata, or image is invalid. `,_jsx(_components.code,{children:`507`}),` means retaining\nthe version would exceed storage capacity. Every retained version, including\nthe original, counts toward storage use.`]}),`\n`,_jsx(_components.li,{children:`The API copies metadata from the original during finalization, so stored\nbytes can differ from your upload. Use the returned version’s checksum and\nURLs when tracking the saved result.`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`See the `,_jsx(_components.strong,{children:`API Reference`}),` tab for endpoint schemas and error responses.`]}),`\n`,_jsx(Heading,{level:`2`,id:`faces-on-edited-photos`,children:`Faces on edited photos`}),`\n`,_jsx(_components.p,{children:`Face boxes are anchored to the original photo’s pixel coordinates. While a\nderived version is current, Gumnut and the Immich adapter hide those boxes\nand reject new manual boxes rather than draw or save them in the wrong place.\nYour existing face and person associations remain attached to the asset.\nRestoring the original makes its face geometry available again.`})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Versioning and editing assets","description":"Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API","href":"/guides/apis/asset-versioning"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Original and derived versions","slug":"original-and-derived-versions","depth":2,"children":[]},{"title":"How editing works","slug":"how-editing-works","depth":2,"children":[]},{"title":"Prerequisites","slug":"prerequisites","depth":2,"children":[]},{"title":"Read the retained versions","slug":"read-the-retained-versions","depth":2,"children":[]},{"title":"Add or replace a derived version","slug":"add-or-replace-a-derived-version","depth":2,"children":[]},{"title":"Restore the original","slug":"restore-the-original","depth":2,"children":[]},{"title":"Handle saves and conflicts","slug":"handle-saves-and-conflicts","depth":2,"children":[]},{"title":"Faces on edited photos","slug":"faces-on-edited-photos","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"gumnutai","siteName":"Gumnut AI","title":"Versioning and editing assets - Gumnut AI","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-20T18:00:22.009Z","originalFileLocation":"guides/apis/asset-versioning.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API\">\u003cmeta data-mint-head name=\"application-name\" content=\"Gumnut AI\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Versioning and editing assets - Gumnut AI\">\u003cmeta data-mint-head property=\"og:description\" content=\"Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Gumnut AI\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.gumnut.ai/guides/apis/asset-versioning\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://gumnutai.mintlify.site/_mintlify/api/og/v2?division=APIs\u0026amp;title=Versioning+and+editing+assets\u0026amp;description=Preserve+asset+identity+and+original+uploads+while+saving%2C+replacing%2C+and+reverting+edited+versions+through+the+API\u0026amp;theme=7a423a7358c492464b4012ea\u0026amp;signature=c00058cd247baee35dba310519c0295bcff6c2750744762d9bd932f7a44610ea\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Versioning and editing assets - Gumnut AI\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://gumnutai.mintlify.site/_mintlify/api/og/v2?division=APIs\u0026amp;title=Versioning+and+editing+assets\u0026amp;description=Preserve+asset+identity+and+original+uploads+while+saving%2C+replacing%2C+and+reverting+edited+versions+through+the+API\u0026amp;theme=7a423a7358c492464b4012ea\u0026amp;signature=c00058cd247baee35dba310519c0295bcff6c2750744762d9bd932f7a44610ea\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/gumnutai/HakcV-TGKbGh8wwG/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Gumnut AI\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#5A4CD6\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.gumnut.ai/guides/apis/asset-versioning\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/guides/apis/asset-versioning.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.gumnut.ai/#organization\",\"name\":\"Gumnut AI\",\"url\":\"https://docs.gumnut.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/gumnutai/g7uvIAJIK6-HCQWp/logo/gumnut-logotype-horizontal-light.svg?fit=max\u0026auto=format\u0026n=g7uvIAJIK6-HCQWp\u0026q=85\u0026s=2a6ec085314f83e9fb98e806c60a6667\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.gumnut.ai#website\",\"name\":\"Gumnut AI\",\"url\":\"https://docs.gumnut.ai\",\"publisher\":{\"@id\":\"https://docs.gumnut.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.gumnut.ai/guides/apis/asset-versioning#webpage\",\"url\":\"https://docs.gumnut.ai/guides/apis/asset-versioning\",\"name\":\"Versioning and editing assets\",\"description\":\"Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API\",\"dateModified\":\"2026-11-20T18:00:22.009Z\",\"isPartOf\":{\"@id\":\"https://docs.gumnut.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.gumnut.ai/guides/apis/asset-versioning#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.gumnut.ai/guides/apis/asset-versioning#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"APIs\",\"item\":\"https://docs.gumnut.ai/guides/apis/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Versioning and editing assets\",\"item\":\"https://docs.gumnut.ai/guides/apis/asset-versioning\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.gumnut.ai/guides/apis/asset-versioning#article\",\"headline\":\"Versioning and editing assets\",\"name\":\"Versioning and editing assets\",\"description\":\"Preserve asset identity and original uploads while saving, replacing, and reverting edited versions through the API\",\"url\":\"https://docs.gumnut.ai/guides/apis/asset-versioning\",\"mainEntityOfPage\":{\"@id\":\"https://docs.gumnut.ai/guides/apis/asset-versioning#webpage\"},\"dateModified\":\"2026-11-20T18:00:22.009Z\",\"publisher\":{\"@id\":\"https://docs.gumnut.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.gumnut.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Gumnut AI\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Gumnut AI\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/guides/apis/asset-versioning.md","siteName":"Gumnut AI","nav":{"global":{"anchors":[{"anchor":"Gumnut Home","icon":"house","href":"https://www.gumnut.ai"}]},"tabs":[{"tab":"Guides","groups":[{"group":"Getting started","pages":[{"title":"Introduction","href":"/guides/getting-started/introduction"},{"title":"Quickstart","href":"/guides/getting-started/quickstart"},{"title":"Import from Google Photos or iCloud","href":"/guides/getting-started/import-from-google-or-apple"}]},{"group":"Product features","pages":[{"title":"Libraries and sharing","href":"/guides/product/libraries"},{"title":"Uploads and processing","href":"/guides/product/uploads"},{"title":"Albums","href":"/guides/product/albums"},{"title":"Searching and filtering","href":"/guides/product/search-and-filtering"},{"title":"Faces and people","href":"/guides/product/people"},{"title":"Map view","href":"/guides/product/map"},{"title":"Stacks and bursts","href":"/guides/product/stacks"},{"title":"Photo editing and versions","href":"/guides/product/editing"},{"title":"AI assistants and integrations","href":"/guides/product/ai-assistants"},{"title":"Duplicate Detection","href":"/guides/product/duplicate-detection"}]},{"group":"Authentication","pages":[{"title":"Authentication","href":"/guides/authentication/overview"},{"title":"API Keys","href":"/guides/authentication/api-keys"},{"title":"OAuth","href":"/guides/authentication/oauth"}]},{"group":"APIs","pages":[{"title":"API Overview","description":"Get started with the Gumnut REST API — explore resources and make your first API calls","href":"/guides/apis/overview"},{"title":"Versioning and editing assets","href":"/guides/apis/asset-versioning"},{"title":"Named Creates and Retries","description":"Safely retry album, person, and library creation when a request may have succeeded","href":"/guides/apis/named-creates"},{"title":"Library Sharing","href":"/guides/apis/library-sharing"},{"title":"People and Faces","href":"/guides/apis/faces-and-people"},{"title":"Requests \u0026 Responses","href":"/guides/apis/requests-and-responses"},{"title":"Pagination \u0026 Filtering","href":"/guides/apis/pagination-and-filtering"},{"title":"Syncing with Events","href":"/guides/apis/syncing-with-events"},{"title":"Rate Limiting","href":"/guides/apis/rate-limiting"}]},{"group":"SDKs","pages":[{"title":"SDKs Overview","href":"/guides/sdks/overview"},{"title":"TypeScript SDK","href":"/guides/sdks/typescript"},{"title":"Python SDK","href":"/guides/sdks/python"}]},{"group":"MCP","pages":[{"title":"MCP Overview","href":"/guides/mcp/overview"},{"title":"MCP Setup","href":"/guides/mcp/setup"},{"title":"MCP Troubleshooting","href":"/guides/mcp/troubleshooting"}]},{"group":"Immich","pages":[{"title":"Immich Overview","href":"/guides/immich/overview"},{"title":"Immich Compatibility","href":"/guides/immich/compatibility"},{"title":"Faces and People","href":"/guides/immich/faces-and-people"},{"title":"Immich Troubleshooting","href":"/guides/immich/troubleshooting"}]},{"group":"More","pages":[{"title":"Demos","href":"/guides/demos/overview"}]}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog/overview"}]},{"tab":"API reference","pages":[{"title":"API reference","href":"/api-reference/assets/list-assets-in-a-library"}]}]},"basePath":"","title":"Versioning and editing assets - Gumnut AI","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}