Illustrator API Key Concepts

Consider these important concepts when using Illustrator APIs.

Pre-signed URLs

What is a pre-signed URL?

A pre-signed URL is a URL that grants temporary access to a specific resource, typically in cloud storage, with predefined permissions and an expiration time. It allows users to upload or download files securely without needing direct access to the storage service's credentials.

While using Illustrator APIs, the input and output assets are stored as pre-signed URLs.

Input assets

The platform supports multiple asset types for input. These asset types indicate storage repositories from which the platform can download. You can provide the input asset information within the assets array.

Illustrator APIs support the following input assets:

• AWS S3: Use a pre-signed GET/PUT/POST URL.

• Dropbox: Generate temporary upload/download links.

• Azure: Use a Shared Access Signature (SAS) in Azure Storage for GET/PUT/POST operations.

"assets" :[
    {
        "source" : {
            "url" : "https://xyz-blob.core.windows.net/Template.ai"
        },
        "destination" : "template1.ai"
    },
    {
        "source" : {
            "url" : "https://s3.eu-west-1.amazonaws/xyz/assets.zip"
        },
        "destination" : "assets.zip"
    }
]

In the examples above, you can see that data is divided into source and destination.

The source attribute is where the asset is downloaded from. The destination attribute refers to where the asset would be downloaded to.

About custom script bundles

To create a script to use with the Custom Scripts API, you'll need to prepare a script bundle, a ZIP file with a predefined structure.

Custom script bundle structure

The structure for a simple custom script bundle would look like this:

custom-script-folder
|------ manifest.json
|------ script.js

Custom Script manifest

The manifest file is a plain JSON file with the following structure:

{
    "manifestVersion": "1.0.0",
    "id": "<Unique ID for the custom script>",
    "name": "<Name of the custom script>",
    "version": "<x.y.z>",
    "host": {
        "app": "illustrator",
        "appVersionStrategy": "latest_version" | "fixed_major_version" | "fixed_major_and_minor_version",
        "majorAppVersion": 20,  // optional depending on strategy
        "minorAppVersion": 1  // optional depending on strategy
    },
    "apiEntryPoints": [
        {
            "type": "capability",
            "path": "script.js",
            "language": "extendscript"
        }
    ]
}

• When a customer registers a script without specifying the strategy, the system automatically chooses latest_version as the default strategy.
• majorAppVersion parameter is mandatory if appVersionStrategy is fixed_major_version.
• majorAppVersion and minorAppVersion are mandatory if appVersionStrategy is fixed_major_and_minor_version.

API Capability Naming Rules

The script name is the name field in your custom script manifest. It identifies your capability when registering and invoking the script. Names must follow the rules below. Any non-compliant names will not be permitted for registration.

Rules

• Length: 3–255 characters.

• Allowed characters (any other character is rejected):

  • Alphanumeric: a-z, A-Z, 0-9
  • Hyphen (-), underscore (_), period (.)
  • Forward slash (/): Allowed only as a segment separator for hierarchical names (for example, renditions/jpeg). Do not use leading or trailing slashes, or consecutive slashes.

Valid name examples

Names that are rejected

The apiEntryPoints field

In the manifest file, the apiEntryPoints attribute is an array of EntryPointDefinition objects with the following format:

• Each entry point specifies a custom script or a custom script specification.
• There can be only one entry of each type in the array.
• The maximum size of the array is 3.

There's no need to define an entry point if the default values are being used for them.

The script.js file

The script's author defines the custom attributes and values for a particular endpoint using script.js file in the custom script bundle.

The execution of any script depends on the following attributes:

For examples, see Custom Script Guide.

Zipping and updating a custom script bundle

When zipping the files, don't place them inside a folder first. Instead, directly select the files and create the ZIP. This way when it's unzipped the files will appear directly instead of appearing inside a folder.

The custom script bundle can be updated by incrementing the version in the script manifest. The updated ZIP bundle can be uploaded using the submission endpoint.