# Media APIs

The @apostrophecms/attachment module manages all media file uploading. Once uploaded, an attachment object should typically be added to an Apostrophe piece or page document (including, but not limited to, @apostrophecms/image and @apostrophecms/file pieces). It is not common, and not generally recommended, to leave uploaded attachments unconnected from any Apostrophe document.

For attachments meant to be included in the media or file libraries, metadata and organization those media are primarily managed through the respective @apostrophecms/image and @apostrophecms/file piece types. See the pieces REST API documentation for additional information.

# Endpoints

Method Path Description Auth required
POST /api/v1/@apostrophecms/attachment/upload Upload a media file TRUE
POST /api/v1/@apostrophecms/attachment/crop Crop an image file TRUE
GET /api/v1/@apostrophecms/image Get an image document with a specified ID FALSE
POST /api/v1/@apostrophecms/image Insert a new image TRUE
GET /api/v1/@apostrophecms/file Get a file document with a specified ID FALSE
POST /api/v1/@apostrophecms/file Insert a new file TRUE

# POST /api/v1/@apostrophecms/attachment/upload

Authentication required.

The body of the request should use the multipart/form-data encoding, with the file itself uploaded under the name file. In a client-side request, the body of the request should be a FormData object.

# Request example

// Create a `FormData` object
const formData = new window.FormData();

// Append a file as per the FormData API:
// https://developer.mozilla.org/en-US/docs/Web/API/FormData/append
formData.append('file', myfile);

// Request inside an async function.
const attachment = await fetch('/api/v1/@apostrophecms/attachment/upload', {
  method: 'POST',
  headers: {
    'Content-Type': 'multipart/form-data'
  },
  body: formData
});

# Response

The successful POST request returns the newly created attachment. In case of an error an appropriate HTTP status code is returned.

Property Format Description
_id String A unique and permanent ID for the attachment
_url String The file URL (the original size, if an image)
_urls Object An object with keys for the generated image size variants, if an image file
archivedDocIds Array An array of string IDs that represent image or file documents using this attachment that are archived
createdAt Date An ISO date string of the attachment's creation date and time
docIds Array An array of string IDs that represent image or file documents using this attachment (empty at initial upload)
extension String The file's file extension, e.g., png, pdf
group String The associated file group, including image or office by default
height Number Height of the image file, if an image
landscape Boolean true if an image with landscape aspect ratio
length Number The file size in bytes
md5 String MD5 checksum value for the file
name String A "slugified" version of the file name (generally lowercased and joined with dashes)
portrait Boolean true if an image with portrait aspect ratio
title String A "sortified" version of the file name (case-insensitive)
type String 'attachment'
updatedAt Date An ISO date string of the attachment's last update date and time
width Number Width of the image file, if an image
// This is a PNG upload with filename `blue-box.png`
{
  "_id": "ckj0akbxa003vp39kfbxgb8zg",
  "group": "images",
  "createdAt": "2020-12-22T17:58:11.314Z",
  "name": "blue-box",
  "title": "blue box",
  "extension": "png",
  "type": "attachment",
  "docIds": [],
  "archivedDocIds": [],
  "length": 10497,
  "md5": "630eeaaecd0bdc07c4a82eeca4c07588",
  "width": 600,
  "height": 106,
  "landscape": true,
  "_urls": {
    "max": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.max.png",
    "full": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.full.png",
    "two-thirds": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.two-thirds.png",
    "one-half": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.one-half.png",
    "one-third": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.one-third.png",
    "one-sixth": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.one-sixth.png",
    "original": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.png"
  }
}

# POST /api/v1/@apostrophecms/attachment/crop

Authentication required.

This route uploads a new, cropped version of an existing image. The crop object is appended to the crops array property of the attachment document.

The body of the request should include:

Property Format Description
_id String The _id property of an existing image attachment document
crop Object An object containing top, left, width and height properties

The newly uploaded image file will be stored with a file name using the crop properties as well as the _id, name, and file extension of the original attachment, formatted as {_id}-{name}.{top}.{left}.{width}.{height}.{extension}

# Response

The successful POST request returns true. In case of an error an appropriate HTTP status code is returned.

# Media GET request

Endpoints:

  • GET /api/v1/@apostrophecms/image
  • GET /api/v1/@apostrophecms/file

A GET request for an image or file is generally a normal piece type GET request. In addition to the typical piece document properties, it will also include an attachment property, containing an object similar to one returned from an attachment upload request.

# Media POST request

Authentication required.

  • POST /api/v1/@apostrophecms/image
  • POST /api/v1/@apostrophecms/file

A POST request for an image or file is generally a normal piece type POST request. In addition to the typical piece document properties, it must also include an attachment property, containing the attachment object returned from an attachment upload request.