Getting Started with Express API

Express API enables you to integrate Adobe Express functionalities into your applications through a REST API. This guide walks you through the setup process, provides usage examples, and outlines best practices.

Overview

The Express API allows you to programmatically interact with Adobe Express documents that have been tagged for automation. By tagging specific elements (text, images, and videos) in your Express documents, you can modify them via API calls to create customized variations and generate renditions.

The Express API endpoints currently only operate on the Express documents tagged for automation workflows. The Tag Elements Add-on facilitates the functionality of tagging elements in an Express document, enabling the document for automation.

Terminology

Prerequisites

Before you begin:

  1. Adobe Express Account: Ensure you have access to Adobe Express

  2. Authentication: Obtain an access token with openid, AdobeID, and ee.express_api scopes. See authentication documentation

  3. API Key: Register your application to receive an API key

  4. Required Headers: Include these in every API request:

    X-API-KEY: "YOUR-API-KEY"
Authorization: "Bearer <Authorization Token>"

Step 1: Preparing Documents for API Access

  1. Install the Add-on:

  2. Create and Tag a Document:

    • Create a new Express document or open an existing one
    • Design your document with the elements you want to modify via API
    • Open the Tag Elements Add-on
    • Select an element (text, image or video)
    • Enter a descriptive tag name in the input field (this will be the identifier in API calls)
    • Click Create tag
    • Repeat for all elements you want to programmatically modify

Step 2: Using the Express API

The Express API provides five key endpoints:

Fetch Tagged Documents Example

This example demonstrates how to retrieve all tagged documents available to your account:

data-slots=heading, code

data-repeat=2

data-languages=CURL, JSON

Request

curl -i -X GET \
  'https://express-api.adobe.io/beta/tagged-documents?start=0&limit=10&sortBy=name' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'X-API-KEY: YOUR-API-KEY'

Response

{
  "documents": [
    {
      "id":"urn:aaid:sc:VA6C2:1ee6d0fe-cd84-590f-b064-285b7d6cc051",
      "name": "My Document.express",
      "thumbnailUrl": "https://aep-cs-blobstore-stage-va6c2-data.s3.amazonaws.com"
    }
  ],
  "paging": {
    "nextUrl": "https://<domain>/beta/tagged-documents?start=1&limit=1&sortBy=name",
    "totalRecords": 1
  }
}

Note: If you receive an empty document list, verify that you have properly tagged your documents.

Fetch Document Details Example

Once you have document IDs, you can retrieve detailed information about a specific document:

data-slots=heading, code

data-repeat=2

data-languages=CURL, JSON

Request

curl -i -X GET \
  'https://express-api.adobe.io/beta/tagged-documents/<YOUR_DOCUMENT_ID>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'X-API-KEY: YOUR-API-KEY'

Response

{
  "name": "MyDocument",
  "id": "urn:aaid:sc:VA6C2:d8638bc5-33d0-3aaf-9e08-9932a8fccf0f",
  "documentPages": [
    {
      "pageNumber": 1,
      "pageTitle": "",
      "thumbnailUrl": "https://aep-cs-blobstore-stage-va6c2-data.s3.amazonaws.com/thumbnail.jpg",
      "size": {
        "width": 1080,
        "height": 1920
      },
      "taggedElements": [
        {
          "name": "logoImage",
          "type": "image",
          "position": {
            "x": 380.13818359375,
            "y": 1211.0332407951355
          },
          "size": {
            "width": 292.2994079589844,
            "height": 222.86627197265625
          }
        },
        {
          "name": "nameLabel",
          "type": "text",
          "position": {
            "x": 386,
            "y": 982.5430908203125
          },
          "size": {
            "width": 252.43186950683594,
            "height": 70.70060157775879
          }
        }
      ]
    }
  ]
}

The response provides detailed information about each tagged element, including its name, type, position, and dimensions. This information is essential when generating document variations.

For detailed examples of generating variations and exporting renditions, see the how-to guides.

Best Practices and Limitations

For optimal results with the Express API:

Next Steps