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 three 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

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

3. Actions and scripts

V1 Endpoints: /pie/psdService/photoshopActions, /pie/psdService/actionJSON, /pie/psdService/productCrop, /pie/psdService/splitView, /pie/psdService/sideBySide, /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

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/splitView → /v2/execute-actions (with published action file)
• /pie/psdService/sideBySide → /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