API for Exporting Outputs

Export a subset of outputs from one or multiple projects in your account defined by specific criteria.

Introduction

With Celtra Export API, you can obtain the desired creative variants from your projects by specifying the required filters and the asset format for export.

Requirements

To be able to request creatives via Celtra Export API, you need to set up authentication.
To authenticate your API request, set up an HTTP Basic Auth service account for personal utility applications. You can then use the Application ID and Secret Key credentials for your application connecting to the Export API. If you want to develop an application that lets multiple users access their data with their own permissions, use OAuth.
Learn how to set up an API Application here, and contact support@celtra.com for more information.
Users need to have access to a specific project to be able to export creatives via Export API.
Reach out to your Account Admin to grant you the project permissions.
To export creatives from your projects, you need to create a POST request, which will then return the assets for requested creatives.

Create a Basic Request

Endpoints

We currently support three endpoints, each returning a response in a different format: JSON (or JSONLines), ZIP and TSV.

JSON

/export will return a list of outputs in a JSON format.

Start by creating a POST request using this link: https://hub.celtra.io/api/export.

Headers

Content-Type - required, where the value field is as follows: application/json; charset=utf-8.
Accept - optional, where the value field must be one of the below:
- application/json (default) - the response will be a JSON (external site) array with output elements [Output, Output, ...]
- application/jsonlines - the response will be JSON Lines (external site) Output\nOutput\n...

Example

Example of exporting all outputs from a design file with ID d1m6jqpdaglh and return a JSON with all output information:

    

    
        
            POST https://hub.celtra.io/api/export
Authorization: Basic <your API App ID> <your API App Secret>
Content-Type: application/json; charset=utf-8

{
   "filters": {
       "designFile": {
           "id": ["d1m6jqpdaglh"]
       },
   }
}

Check out more examples here and learn more about different request options here.

ZIP

/exportToZip will return a zip file that includes assets of exported outputs.

Start by creating a POST request using this link: https://hub.celtra.io/api/exportToZip.

Headers

Content-Type: application/json; charset=utf-8.

Endpoint specific parameters

filename (optional) - give the resulting zip a specific name (default value if not specified: “export”)

Example

Example of exporting all outputs from a design file with ID d1m6jqpdaglh and return a ZIP named “Exported outputs.zip” with all outputs in the zip.

    

    
        
            POST https://hub.celtra.io/api/exportToZip
Authorization: Basic <your API App ID> <your API App Secret>
Content-Type: application/json; charset=utf-8

{
   "filters": {
       "designFile": {
           "id": ["d1m6jqpdaglh"]
       },
   },
   "filename": "Exported outputs"
}

Check out more examples here and learn more about different request options here.

TSV

/exportToTsv will return a TSV file that includes assets of exported outputs, either just the TSV file with links to assets or a zip with TSV and assets beside it.

Start by creating a POST request using this link: https://hub.celtra.io/api/exportToTsv.

Headers

Content-Type: application/json; charset=utf-8.

Endpoint specific parameters

responseFormat - optional - possible values are “urls” (default if not specified) or “paths”, and define if the result is a TSV with links to assets or if TSV is returned in a zip with all assets also in the zip;
filename (optional) - give the resulting file a specific name (default value if not specified: “export”)

Example

Example of exporting all outputs from a design file with ID d1m6jqpdaglh and returning a TSV file with all output information:

    

    
        
            POST https://hub.celtra.io/api/exportToTsv
Authorization: Basic <your API App ID> <your API App Secret>
Content-Type: application/json; charset=utf-8

{
   "filters": {
       "designFile": {
           "id": ["d1m6jqpdaglh"]
       },
   },
   "responseFormat": "urls",
   "filename": "Exported outputs"
}

Check out more examples here and learn more about different request options here.

Request Options

The request payload can be adjusted to give you the power to specify what outputs exactly to export and to specify the resulting format.

Specifying a filter is required, and specifying other options is not.

    

    
        
            type Request = {
	filters: Filters,
	assetFormats?: AssetFormats,
	caller?: string
}

filters - define what outputs to export. More about defining `filters` can be found here.

assetFormats (optional) - define the format in which the returned outputs should be. More about defining `assetFormat` can be found here.

caller (optional) - define a custom string value that identifies where the calls are coming from. You can assign a value that is relevant to your use case (for example, hannahFacebookIntegrationScript), and if you have any issues with the API, provide this string to make our troubleshooting your case easier.

Example

    

    
        
            POST https://hub.celtra.io/api/export
Authorization: Basic <your API App ID> <your API App Secret>
Content-Type: application/json; charset=utf-8

{
   "filters": {
       "designFile": {
           "id": ["d1m6jqpdaglh"]
       },
   },
   "assetFormats": {
      "Image": {
           "image": {
               "format": "png",
               "quality": 8
           }
       }
   },
   "caller": "hannahFacebookIntegrationScript"
}

Filters

Filters define the desired set of outputs.

Refer here for the output entity.

Each request needs to include at least one of the following filters:

designFile.id
folder.id
account.id and designFile.lastModificationTimestamp

To avoid errors, adjust the filters to match your access level when using Celtra Export API. For instance, if you only have access to a single project, make sure to set the filters accordingly instead of requesting creatives from the entire account.

The following syntax should be applied for filters:

    

    
        
            /**
 * pathComponent is a valid path component in Output
 */
type Filters = { [pathComponent: string]?: Filters } | Leaf
type Leaf = ValidValue[]
type Scalar = string | number | boolean | null
type ValidValue =
	| { eq?: Scalar, gt?: Scalar, gte?: Scalar, lt?: Scalar, lte?: Scalar, object?: object }
	| Scalar // equivalent to { eq: Scalar }

Where the above-mentioned values stand for the following:

`eq`	equal to
`gt`	greater than
`gte`	greater than or equal
`lt`	less than
`lte`	less than or equal
`object`	subobject of

Let’s take a look at a request example that shows how filters should be applied. We’ll use an example where we want returned Image outputs in English and French that belong to a design file for which we want to specify the time when it was modified.

The body of the request should look like this:

    

    
        
            {
    "filters": {
        "account": {
            "id": ["fe33bb6a"]
        },
        "designFile": {
            "id": ["b6bc20ae"],
            "lastModificationTimestamp": [
                {"gt": "2023-03-01 00:00:00"}
            ]
        },
        "output": {
            "mediaLineItem": {
                "formatRegistrationId": ["com.celtra.image"]
            },
            "contentDimensionsByName": {
                "Language": ["en", "fr"]
            }
        }
    }
}

The Content variations and their variants' names (for example: Language en, fr) are case-sensitive.
These refer to scaling dimensions configured at the design file setup level.
All Key and Value properties need to be double-quoted inside the request’s body.

Asset Formats

Depending on the output format, the following asset formats are supported and can be specified in a request:

    

    
        
            type AssetFormats = {
    Image?: {
        image?: ImageAssetFormat = { format: string }
    },
	HTML?: {
        html?: HtmlAssetFormat = { adServer: string }
    }
}

type ImageAssetFormat =
        /** RGBA, 8 bits per channel, sRGB color space */
        | {
              format: 'png',
              /** Convert PNG file colors to a limited palette of 2-256 colors to reduce file size. */
              colors?: number,
          }
        | { format:'jpeg', quality?: number, maxSizeKb?: number }
        | { format: 'tiff' }
        | { format: 'webp' }

type HtmlAssetFormat = 
    | { adServer: 'generic' }
    | { adServer: 'flashtalking' }
    | { adServer: 'googleAds' }
    | { adServer: 'googleAdsUac' }
    | { adServer: 'googleAdManager' }
    | { adServer: 'campaignManager360' }
    | { adServer: 'displayVideo360' }
    | { adServer: 'dcStudio' }
    | { adServer: 'ttd' }
    | { adServer: 'revjet' }
    | { adServer: 'simplifi' }
    | { adServer: 'xandr' }
    | { adServer: 'liftoff' }
    | { adServer: 'adform' }
	| { adServer: 'innovid' }

The body with custom asset formats should look something like this:

    

    
        
            {
    "filters": ...,
    "assetFormats": {
      "Image": {
           "image": {
               "format": "png",
               "quality": 8
           }
       },
       "HTML": {
           "html": {
               "adServer": "generic"
           }
       }
   }
}

Response

JSON

The response is a JSON array or JSON Lines document, depending on the above-mentioned Accept request header specification.

The response is an array of outputs.

    

    
        
            type Response = Output[]

Here’s a preview of the response for a single output requested in our above example:

ZIP

The response is an exported ZIP file of all variants.

TSV

The response is either a single TSV file containing links to assets or a ZIP file that includes both the TSV file and the asset files.

Response Status Codes

The possible response status codes are as follows:

`200 OK`	The processing of the assets is either in progress or completed.
`400 Bad Request`	The request is invalid. The response body will include additional information.
`403 Forbidden`	The user cannot export at least one of the requested outputs.
`500 Internal Server Error`	An unhandled exception error has occurred. Please reach out to support@celtra.com.

Output Entity

The main entity used in Export API is Output. This is the base used for filtering and output response in JSON.

    

    
        
            type Output = {
    id: string
    name: string | null
     /**
     * Whether all the output's async assets are ready (not pending).
     * pending: At least one of the async assets is still pending.
     * error: No assets are pending but at least one is in error state.
     * finished: All assets have been processed successfully.
     *
     * Cannot be used for filtering at the moment.
     */
    status: 'pending' | 'error' | 'finished',
     * A link to preview, appropriate for end users. Unlike assets, does not expire,
     * however may stop working if the output no longer exists.
     *
     * Cannot be used for filtering at the moment.
     */
    previewUrl: string,

    // Related entities
    //
    // All of them have a unique id property.
    // Values with the same id are guaranteed to be the same.
    account: {
        id: string,
        name: string,
    },
    folder: {
        id: string,
        name: string,
    	/**
     	 * Convenience dictionaries of key value pairs assuming unique key and value names.
     	 */
    	customAttributesByName: {
       		[name: string]: string,
    	},
    },
    designFile: {
        id: string,
        name: string,
        lastModificationTimestamp: Timestamp,
		contentBlobHash: string,
        customAttributesByName: {
       		[name: string]: string,
    	},
    },
    customLayoutDimensions: {
        [id: string]: {
            id: string,
            name: string,
            value: {
                id: string,
                name: string,
            },
            attributes: {
                [id: string]: {
                    id: string,
                    name: string,
                    value: {
                        id: string,
                        name: string,
                    },
                },
            }
        },
    },
    contentDimensions: {
        [id: string]: {
            id: string,
            name: string,
            value: {
                id: string,
                name: string,
            },
        },
    },
    mediaLineItemAttributes:
        [id: string]: {
            id: string,
            name: string,
            value: {
                id: string,
                name: string,
            },
        },
    },
    /**
     * Convenience dictionaries of key value pairs assuming unique key and value names.
     * If multiple keys or values share the same name, only one will be returned.
     */
    customLayoutDimensionsByName: {
        [name: string]: string,
    },
    contentDimensionsByName: {
        [name: string]: string,
    },
    mediaLineItemAttributesByName: {
        [name: string]: string,
    },
    contentAttributesByName: {
        [name: string]: {
            [name: string]: string,
        },
    },
	activation: {
        id: string,
        name: string,
        markedAsTemplate: boolean
    } | null
	mediaLineItem: {
        id: string,
        name: string,
        formatRegistrationId: FormatRegistrationId,
    },
} & (
    // Format-specific data
    {
        assets: {
            image: ImageAsset,
            [name: string]: TextAsset,
        },
    } |
    {
        assets: {
             video: VideoAsset,
		     [name: string]: TextAsset,
    } | {
        assets: {
            [name: string]: CardAsset,
            [name: string]: TextAsset,
        },
    } | {
        assets: {
            html: HtmlAsset,
            fallbackImage?: FileAsset,
        },
    },
)

Where FormatRegistrationId is:

    

    
        
            type FormatRegistrationId =
| "com.celtra.image" // custom image
| "com.celtra.video" // custom video
| "com.celtra.html" // custom html
| "com.celtra.meta.image" // Meta specific image
| "com.celtra.meta.video" // Meta specific video
| "com.celtra.meta.carousel" // Meta specific carousel
| "com.celtra.youtube.video" // YouTube specific video

Where AsyncAsset is:

    

    
        
            type AsyncAsset =
| { status: "pending" }
| { status: "finished", url: string, blobHash: string, extension: string }
| { status: "error", error: string }

The URL is valid for 30 days after being returned by the server.

Where TextAsset is:

    

    
        
            type TextAsset = {
    type: "Text",
    text: string,
}

Where ImageAsset is:

    

    
        
            type ImageAsset = {
    type: 'Image',
	width: number,
    height: number,
} & AsyncAsset

Where VideoAsset is:

    

    
        
            type VideoAsset = {
    type: 'Video',
    width: number,
    height: number,
    fps: number,
    duration: number,
} & AsyncAsset

Where CardAsset is:

    

    
        
            type CardAsset = ImageAsset | VideoAsset

Where HtmlAsset is:

    

    
        
            type HtmlAsset = {
    type: 'HTML',
    width: number,
    height: number,
    fps: number,
    duration: number,
} & AsyncAsset

Where FileAsset is:

    

    
        
            type FileAsset = {
    type: 'File',
} & AsyncAsset

Where Timestamp is:

    

    
        
            type Timestamp = string // ISO 8601 standard, eg: “2020-12-31 23:59:59”

Usage Examples

Check out the below list of Related Articles for different use cases.

API for Exporting Outputs open Created with Sketch.

Introduction

Requirements

Create a Basic Request

Endpoints

JSON

Headers

Example

ZIP

Headers

Endpoint specific parameters

Example

TSV

Headers

Endpoint specific parameters

Example

Request Options

Example

Filters

Asset Formats

Response

JSON

ZIP

TSV

Response Status Codes

Output Entity

Usage Examples

API for Exporting Outputs