File tags

Replace a file tag

Replaces the whole document: every field left out is reset to its default. PATCH changes only the fields sent. Completely replace a specific file tag by ID using PUT semantics

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

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

PUT

@apostrophecms

file-tag

{_id}

cURL

curl --request PUT \
  --url https://{host}/api/v1/@apostrophecms/file-tag/{_id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Marketing Materials",
  "slug": "marketing-materials"
}
'

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

const site = createSiteClient();
const fileTag = await site.media().replaceFileTag({ id: 'ckitdo5oq004pu69kr6oxo6fr:en:published', title: 'Marketing Materials' });

{
  "_id": "clx1234567890abcdef",
  "title": "Marketing Materials",
  "slug": "marketing-materials",
  "type": "@apostrophecms/file-tag",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "archived": false,
  "copyOfId": "ckhdscx5900054z9k88uqs16w:en:published",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

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

Scopes

content:files:write

Path Parameters

_id

string

required

Computed document ID (can optionally include mode and locale, e.g., id:en:published)

Pattern: ^\S+$

Example:

"ckitdo5oq004pu69kr6oxo6fr:en:published"

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 tag piece type for organizing files

title

string

required

Tag name

Example:

"Marketing Materials"

slug

string

required

URL-friendly tag name

Example:

"marketing-materials"

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.

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"

Response

File tag replaced successfully

Built-in file tag piece type for organizing files

_id

string

required

read-only

Example:

"clx1234567890abcdef"

title

string

required

Tag name

Example:

"Marketing Materials"

slug

string

required

URL-friendly tag name

Example:

"marketing-materials"

type

string

required

read-only

Example:

"@apostrophecms/file-tag"

createdAt

string<date-time>

required

read-only

updatedAt

string<date-time>

required

read-only

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.

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"

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 PUT \
  --url https://{host}/api/v1/@apostrophecms/file-tag/{_id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Marketing Materials",
  "slug": "marketing-materials"
}
'

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

const site = createSiteClient();
const fileTag = await site.media().replaceFileTag({ id: 'ckitdo5oq004pu69kr6oxo6fr:en:published', title: 'Marketing Materials' });

{
  "_id": "clx1234567890abcdef",
  "title": "Marketing Materials",
  "slug": "marketing-materials",
  "type": "@apostrophecms/file-tag",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "archived": false,
  "copyOfId": "ckhdscx5900054z9k88uqs16w:en:published",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

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

Replace a file tag

Authorizations

Scopes

Path Parameters

Query Parameters

Body

Response