Attachments

Upload media file

Upload a media file to create an attachment. The uploaded file can then be used to create image or file documents. Uses multipart/form-data encoding with the file uploaded under the name ‘file’.

Access: an API key with any one of content:images:write, content:files:write or content:videos:write (or a master above one). A signed-in person may call it as far as their own permissions allow; anyone else gets 403.

Signing: a key whose signing mode covers writes signs this upload by its SHA-256: send the hex digest of the exact body bytes in X-Fetchski-Content-SHA256 and sign that digest in the body’s place (<timestamp>.POST.<path+query>.<digest>). The site checks the signature before it reads the upload, then the bytes against the digest. The SDKs do this for you. Signing requests shows how, from the API and both SDKs.

Rate limit: the key’s own writes-per-minute limit, set when the key is created (default 120); over it, 429 with Retry-After.

POST

@apostrophecms

attachment

upload

cURL

curl --request POST \
  --url https://{host}/api/v1/@apostrophecms/attachment/upload \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@example-file;type=image/*'

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const attachment = await site.attachments().uploadAttachment({ file: new File(['…'], 'photo.jpg', { type: 'image/jpeg' }) });

{
  "_id": "ckj0akbxa003vp39kfbxgb8zg",
  "_url": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.png",
  "_urls": {},
  "name": "blue-box",
  "title": "blue box",
  "extension": "png",
  "type": "attachment",
  "group": "images",
  "length": 10497,
  "md5": "630eeaaecd0bdc07c4a82eeca4c07588",
  "width": 600,
  "height": 106,
  "landscape": true,
  "portrait": true,
  "docIds": [
    "<string>"
  ],
  "archivedDocIds": [
    "<string>"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "_isCroppable": true,
  "crop": {},
  "used": true,
  "folderId": "<string>",
  "folderPath": "<string>"
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

Authorizations

Authorization

string

header

required

Paste your API key as the CMS showed it: fsk_<site>_<key id>_<secret> (issued under API Keys). ApiKey in front of it works too. Leave it empty to read as the public.

Query Parameters

aposMode

enum<string>

default:published

published (the default) or draft. Drafts need a credential that may see them: an API key with the type’s write scope (content:<type>:write), or a signed-in editor. The public and a key with only the read scope get 403.

Available options:

draft,

published

aposLocale

string

The locale to read or write, e.g. en (default: the site’s default locale).

Example:

"fr"

Body

multipart/form-data

file

required

The file to upload

Response

File uploaded successfully

File attachment information from upload endpoint

_id

string

Unique attachment identifier

Example:

"ckj0akbxa003vp39kfbxgb8zg"

_url

string

The file’s URL: set for a file that is not an image. An image’s URLs are in _urls, by size (original is the file as uploaded).

Example:

"https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.png"

_urls

object

An image’s URLs by size (original, max, full, two-thirds, one-half, one-third, one-sixth); unset for other files.

Show child attributes

name

string

Slugified filename

Example:

"blue-box"

title

string

Sortified filename

Example:

"blue box"

extension

string

File extension

Example:

"png"

type

string

Always attachment.

Example:

"attachment"

group

string

File group type

Example:

"images"

length

integer

File size in bytes

Example:

10497

md5

string

MD5 checksum

Example:

"630eeaaecd0bdc07c4a82eeca4c07588"

width

integer

Image width in pixels (images only)

Example:

600

height

integer

Image height in pixels (images only)

Example:

106

landscape

boolean

Whether image is landscape orientation (images only)

portrait

boolean

Whether image is portrait orientation (images only)

docIds

string[]

IDs of documents using this attachment

archivedDocIds

string[]

IDs of archived documents using this attachment

createdAt

string<date-time>

When it was uploaded (ISO 8601).

updatedAt

string<date-time>

When it last changed (ISO 8601).

_isCroppable

boolean

Whether the image can be cropped.

crop

object | null

The crop applied, if any (top, left, width, height).

used

boolean

Whether any document uses the file.

folderId

string | null

The media folder holding the file, by its aposDocId.

folderPath

string

That folder’s path, e.g. events/summer.

cURL

curl --request POST \
  --url https://{host}/api/v1/@apostrophecms/attachment/upload \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@example-file;type=image/*'

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const attachment = await site.attachments().uploadAttachment({ file: new File(['…'], 'photo.jpg', { type: 'image/jpeg' }) });

{
  "_id": "ckj0akbxa003vp39kfbxgb8zg",
  "_url": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.png",
  "_urls": {},
  "name": "blue-box",
  "title": "blue box",
  "extension": "png",
  "type": "attachment",
  "group": "images",
  "length": 10497,
  "md5": "630eeaaecd0bdc07c4a82eeca4c07588",
  "width": 600,
  "height": 106,
  "landscape": true,
  "portrait": true,
  "docIds": [
    "<string>"
  ],
  "archivedDocIds": [
    "<string>"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "_isCroppable": true,
  "crop": {},
  "used": true,
  "folderId": "<string>",
  "folderPath": "<string>"
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

Get started

How the API works

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Signing in (people)

Upload media file

Authorizations

Query Parameters

Body

Response