V2 API behavior catalog

This page is a comprehensive per-endpoint behavioral reference for developers migrating from V1 to V2. For each endpoint group it covers: what V1 did, what V2 does, a table of behavioral changes, and links to detailed guides.

For a positive framing of net new capabilities (things you couldn't do at all in V1), see What's New in V2.

1. Edit operations

V1 Endpoints: /lrService/autoTone, /lrService/autoStraighten, /lrService/presets, /lrService/xmp, /lrService/edit

V2 Endpoint: /v2/edit

V1 behavior

V1 Lightroom operations were individual endpoints: one endpoint per operation type. To apply multiple adjustments you made multiple sequential API calls, each returning a job ID to poll. Inputs used inputs[].href + storage discriminant. The options block held adjustment parameters.

V2 behavior

All Lightroom edit operations are unified under /v2/edit. You can combine any number of adjustments — autoTone, autoStraighten, light, color, detail, effects, optics, XMP presets — in a single request. The adjustment parameter names and value ranges are identical to V1; only the envelope changed.

Behavioral changes

Guide

Edit Operations Migration

2. Composite and layer operations

V1 Endpoints: /pie/psdService/renditionCreate, /pie/psdService/documentCreate, /pie/psdService/documentOperations, layer operations via documentOperations

V2 Endpoint: /v2/create-composite

V1 behavior

V1 used four separate endpoints for what are now unified operations:

• renditionCreate — convert PSD to JPEG/PNG/TIFF (format conversion only)
• documentCreate — create a new blank document
• documentOperations — modify existing documents: resize, crop, trim, add/edit/delete layers
• smartObject — dedicated endpoint for placing or replacing smart object content

Layer operations were specified as an options.layers array within documentOperations. Layer types used camelCase names (layerSection, textLayer, smartObject).

V2 behavior

All three operations are unified under /v2/create-composite. The request structure uses image.source for input, edits for operations, and outputs for results. Layer types use snake_case names. Processing order is strictly top-down through the edits.layers array — layer position is not determined by array index alone.

Behavioral changes

Guide

Layer Operations Overview — then choose a sub-guide:

• Image Layers
• Text Layers
• Adjustment Layers
• Smart Objects
• Advanced Operations
• Document Creation
• Document Operations
• Format Conversion

For the dedicated V1 /psdService/smartObject endpoint: Smart Object Place/Replace Migration

3. Actions and scripts

V1 Endpoints: /pie/psdService/photoshopActions, /pie/psdService/actionJSON, /pie/psdService/productCrop, /pie/psdService/depthBlur

V2 Endpoint: /v2/execute-actions

V1 behavior

V1 had separate endpoints for each action type: photoshopActions for .atn files, actionJSON for inline action commands, and dedicated convenience endpoints for specific operations (product crop, split view, etc.). Convenience endpoints used hidden server-side action files that developers could not inspect or modify.

V2 behavior

All action types are unified under /v2/execute-actions. The options block contains an array of action objects with a type discriminant ("photoshopActions", "actionJSON", "uxp"). UXP scripts (ES6+ JavaScript) are a new option alongside the existing action types. The action files used by V1 convenience APIs are now published and accessible via additionalContents.

data-variant=warning

data-slots=text

Behavioral changes

Guide

Actions Migration

For the dedicated V1 /psdService/text endpoint: Text Layer Operations Migration

4. Manifest generation

V1 Endpoint: /pie/psdService/documentManifest

V2 Endpoint: /v2/generate-manifest

V1 behavior

V1 documentManifest returned a layer tree with basic per-layer information: name, type (camelCase), bounds (height/width/left/top format), a presigned S3 thumbnail URL string, and simple locked boolean. Artboards were indistinguishable from group layers. Smart objects had a flat structure with instanceId, name, path, and MIME-type type. The document block had bitDepth, iccProfileName, name.

V2 behavior

V2 generate-manifest returns a much richer layer tree. Layer type names are renamed to snake_case. Bounds use {left, top, right, bottom} format. Thumbnails return as {mediaType, url} objects pointing to /v2/short-url/ redirects. Artboards are a distinct type: "artboard" with full geometry and preset data. Smart objects expose extracted.url for embedded content download. The document block gains xmp, resolution, globalLightingAngle, and other fields.

Layer type renames

Behavioral changes

For a complete field-by-field reference, see Manifest Response Migration.

Guide

Manifest Migration · Manifest Response Migration

5. Artboard creation

V1 Endpoint: /pie/psdService/artboardCreate

V2 Endpoint: /v2/create-artboard

V1 behavior

V1 artboardCreate accepted a flat list of input images and created a new PSD with one artboard per image. Images were specified in the top-level inputs[] array alongside output configuration.

V2 behavior

V2 /v2/create-artboard uses a dedicated images[] array where each entry has a source object for the input and id for ordering. Artboard spacing is configurable via artboardSpacing. The request follows the standard V2 envelope with outputs[].

Behavioral changes

Guide

Artboard Migration

6. Job status

V1 Endpoints: /pie/psdService/status/{jobId}, /lrService/status/{jobId}

V2 Endpoint: /v2/status/{jobId}

V1 behavior

Each V1 service had its own status endpoint. Photoshop jobs used /pie/psdService/status/{jobId}; Lightroom jobs used /lrService/status/{jobId}. Status responses were service-specific in structure.

V2 behavior

All V2 jobs use a single /v2/status/{jobId} endpoint regardless of which operation created the job. The response includes a status field (pending, running, succeeded, failed), an outputs array with per-output status and destination URLs, and a structured errors array.

Behavioral changes

Guide

Status Migration

7. Cross-cutting changes

These changes apply to all V2 endpoints.

Base URLs

Request structure

Storage options

data-variant=info

data-slots=text

Output format changes

Error response structure

V2 errors use a consistent structure across all endpoints:

{
  "errors": [
    {
      "code": "INPUT_EXCEEDS_MAX_SIZE",
      "message": "Input file exceeds maximum allowed size of 100MB"
    }
  ]
}

V1 error structures varied by service.

Guide

Output Types Migration · ICC Profile Migration · Storage Solutions

8. Breaking changes checklist

Use this list to audit your codebase for required V2 changes.

Authentication and connectivity

• Update base URL from image*.adobe.io to photoshop-api*.adobe.io
• Authentication credentials are unchanged — no action needed

Request structure

• Replace inputs[0].href + "storage" with image.source.url
• Replace options block with edits (for composite/document) or top-level fields (for edit)
• Replace outputs[0].href + "storage" with outputs[0].destination.url (or embedded/hosted)
• Replace "type": "image/jpeg" with "mediaType": "image/jpeg" in outputs

Endpoint changes

• All /lrService/* calls → /v2/edit
• /pie/psdService/renditionCreate → /v2/create-composite
• /pie/psdService/documentCreate → /v2/create-composite
• /pie/psdService/documentOperations → /v2/create-composite
• /pie/psdService/photoshopActions → /v2/execute-actions
• /pie/psdService/actionJSON → /v2/execute-actions
• /pie/psdService/productCrop → /v2/execute-actions (with published action file)
• /pie/psdService/artboardCreate → /v2/create-artboard
• /pie/psdService/documentManifest → /v2/generate-manifest
• /pie/psdService/status/{jobId} → /v2/status/{jobId}
• /lrService/status/{jobId} → /v2/status/{jobId}

Action requests

• Add options[].type discriminant ("photoshopActions", "actionJSON", "uxp")
• Move action file reference to options[].photoshopAction.source.url
• Move inline ActionJSON to options[].actionJSON.commands

Layer operation requests

• Add operation.type field to each layer operation ("add", "edit", "delete", "move")
• Rename layer types in requests: layerSection → group_layer, textLayer → text_layer, smartObject → smart_object_layer, fillLayer → solid_color_layer (creating a new document with a group layer is not yet supported — upcoming feature; editing an existing document to add a layer inside a group is supported — use into + referenceLayer)
• Replace locked: true with protection: ["all"]

Manifest response parsing

• Update layer type string comparisons (camelCase → snake_case); expect background as background_layer (no typeAttributes on background entries)
• Update bounds parsing: drop height/width, compute from {left, top, right, bottom}
• Update thumbnail parsing: plain string → {mediaType, url} object
• Update mask field access → pixelMask; offset.x/y → offset.horizontal/vertical
• Update locked boolean → protection array
• Update artboard traversal: children under layers[] not children[]
• Update smart object parsing: flat → nested smartObjectData.fileInfo.*
• Update document field names: bitDepth → depth, iccProfileName → iccProfile, name → title

Output format

• Replace numeric JPEG quality values with string enums (7 → "maximum", etc.)
• Update PNG compression range if using values above 2

See also

• What's New in V2 — Net new capabilities framed positively
• Migration Overview — Architectural rationale
• Quick Reference — Endpoint mapping table
• LLM Migration Reference — Consolidated reference for AI-assisted migration