How-to library · Developer docs

How-to library

Task-shaped pages: a title that starts with a verb, the situation in a few lines, the steps, the working code in both engines, and why this way rather than another. Found from a search, done, and left.

How-to Images

Upload an image and place it in an area

Published

POST the file to /cdna-api/files/upload-file as multipart form data, with a folder and type=image; the answer carries the image's id. Put that id in an image area, or an image custom field, and read the layout area back for the image's path.

Context

Context. An import brings product photos, a form of your own collects a logo, a script builds pages that each need a hero image. Images belong in the site's file library, not on another server, so each one is uploaded first and then referred to by its id wherever it is used.

Before you start

Credentials for a backend user who may add files and edit the record, the file on your server, and the folder to put it in. The folder path is created if it does not exist yet.

Steps

  1. Send the file as multipart/form-data to POST /cdna-api/files/upload-file: the file in the part fileToUpload, folder with the path, and type=image. filename sets another name than the file's own. A folder that does not exist yet is created.
  2. Decide what a second upload to the same path does, with duplicate: error refuses it with a 409, update makes a new revision of the existing image, rename stores it beside the first with a number added (photo-1.png), and use returns the existing image when the file is identical and otherwise renames like rename. Without it, the site's default strategy applies.
  3. Keep the id from the answer.
  4. Put the id in an image area, here in a figure component added to a page's sections, or in an image custom field ("customFields": {"heroImage": 1185}).
  5. Read the layout area back: it gives imageId and imagePath, the path to build image URLs and sizes from.

Code

Shell Upload: real answers from this documentation site 
curl -X POST 'https://www.example.com/cdna-api/files/upload-file' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'fileToUpload=@api-sandbox-figure.png;type=image/png' \
  --form 'folder=images/api-sandbox' \
  --form 'type=image' \
  --form 'duplicate=error'

# 200 {"error":"","type":"image","file":"/files/images/api-sandbox/api-sandbox-figure.png","link":"/files/images/api-sandbox/api-sandbox-figure.png","id":1185}
# the same again:
# 409 {"error":"An image already exists at the specified path. Specify a different duplicate strategy with duplicate=update, duplicate=rename, duplicate=smart or a different file name."}
HTTP Place it in an image area 
PUT /cdna-api/pages/page/1885?properties={id,activeRevision{id}}
Content-Type: application/json

{
  "patchRevision": {
    "originRevision": 3447,
    "activeRevision": true,
    "appendAreaCollectionElement(pageSections)": {
      "layout": 58,
      "name": "Sandbox figure",
      "areas": {"image": 1185, "alt": "A blue and green gradient", "caption": "Uploaded through the API"}
    }
  }
}
JSON The image area, read back with activeRevision{areasContent} 
"image": {"id": 90803, "type": "Image", "category": "image", "imageId": 1185, "imagePath": "/files/images/api-sandbox/api-sandbox-figure.png"}

Why this and not that

Not a remote URL in the layout area: an image area holds an image from the site's own library, by id, and that is what lets the platform resize and serve it. Images hotlinked inside rich text are a different case, handled by the import setting in the related how-to. Not duplicate=smart, although the 409's message suggests it: this route accepts only use, update, rename and error, and anything else falls back to the site's default. Not a base64 string in a JSON body: this route reads a file part, and base64 makes the request a third larger. And for an import, upload each image once with duplicate=use and keep a map from the source's file names to ids, rather than uploading the same file for every record that uses it.

Go deeper
GuideWriting areas GuideFolders, filenames and file revisions How-toImport a legacy site's externally hosted images during a migration How-toResize an image from JavaScript using URL parameters ReferenceUpload a file: API reference

Was this page helpful?

Your answer goes to the docs team.