Create a file

POST

@apostrophecms

file

cURL

curl --request POST \
  --url https://{host}/api/v1/@apostrophecms/file \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "_id": "clx1234567890abcdef",
  "type": "@apostrophecms/file",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "title": "Company Brochure",
  "slug": "company-brochure",
  "archived": false,
  "visibility": "public",
  "attachment": {
    "_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>"
  },
  "description": "<string>",
  "copyOfId": "ckhdscx5900054z9k88uqs16w:en:published",
  "_folder": [
    {}
  ],
  "_tags": [
    {}
  ],
  "_url": "<string>",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

{
  "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.

Scopes

content:files:write

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

application/json

Built-in file piece type for general file uploads (PDFs, documents, etc.)

title

string | null

File title/description

Example:

"Company Brochure"

slug

string

Its URL name: lowercase words joined by hyphens.

Example:

"company-brochure"

archived

boolean | null

default:false

In the archive: kept, but out of every list and off the site until it is restored. false (or null) for a live document.

visibility

enum<string>

default:public

Who may see it on the site: public (everyone) or loginRequired (signed-in people only).

Available options:

public,

loginRequired

attachment

Attachment · object

The file itself: its URLs (_urls by size for an image, _url for another file), size and dimensions.

Show child attributes

description

string | null

File description

copyOfId

string | null

The _id of the piece/page that was copied to create this document (only present if created via _copyingId)

Example:

"ckhdscx5900054z9k88uqs16w:en:published"

_folder

object[] | null

The media folder holding it (one at most; empty at the library’s root).

_tags

object[] | null

Its tags, as documents.

_url

string<uri> | null

The file’s URL (the attachment’s _url).

Response

File created successfully

Built-in file piece type for general file uploads (PDFs, documents, etc.)

_id

string

required

read-only

Unique identifier

Example:

"clx1234567890abcdef"

type

string

required

read-only

Example:

"@apostrophecms/file"

createdAt

string<date-time>

required

read-only

updatedAt

string<date-time>

required

read-only

title

string | null

File title/description

Example:

"Company Brochure"

slug

string

Its URL name: lowercase words joined by hyphens.

Example:

"company-brochure"

archived

boolean | null

default:false

In the archive: kept, but out of every list and off the site until it is restored. false (or null) for a live document.

visibility

enum<string>

default:public

Who may see it on the site: public (everyone) or loginRequired (signed-in people only).

Available options:

public,

loginRequired

attachment

Attachment · object

The file itself: its URLs (_urls by size for an image, _url for another file), size and dimensions.

Show child attributes

description

string | null

File description

copyOfId

string | null

The _id of the piece/page that was copied to create this document (only present if created via _copyingId)

Example:

"ckhdscx5900054z9k88uqs16w:en:published"

_folder

object[] | null

The media folder holding it (one at most; empty at the library’s root).

_tags

object[] | null

Its tags, as documents.

_url

string<uri> | null

The file’s URL (the attachment’s _url).

The draft’s preview share key, while its share link is on: the link is the draft’s _url with aposShareKey and aposShareId (the draft’s _id) in its query. Absent otherwise, and on published documents.

Example:

"k3v9x2m7q1z8w4p6"

cURL

curl --request POST \
  --url https://{host}/api/v1/@apostrophecms/file \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "_id": "clx1234567890abcdef",
  "type": "@apostrophecms/file",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "title": "Company Brochure",
  "slug": "company-brochure",
  "archived": false,
  "visibility": "public",
  "attachment": {
    "_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>"
  },
  "description": "<string>",
  "copyOfId": "ckhdscx5900054z9k88uqs16w:en:published",
  "_folder": [
    {}
  ],
  "_tags": [
    {}
  ],
  "_url": "<string>",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

{
  "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)

Authorizations

Scopes

Query Parameters

Body

Response