Instagram Posts

Replace an Instagram post

Replaces the whole document: every field left out is reset to its default. PATCH changes only the fields sent. Update an existing Instagram post.

Access: an API key with content:instagram-posts:write (or a master above it: content:instagram-posts:all, content:all, admin:all). In published mode (the default) it goes live too, so the key also needs content:instagram-posts:publish (or a master above it); send aposMode=draft (or a draft _id and no aposMode) to change only the draft. 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

instagram-post

{_id}

cURL

curl --request PUT \
  --url https://{host}/api/v1/instagram-post/{_id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "",
  "slug": ""
}
'

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

const site = createSiteClient();
const instagramPost = await site.instagramPosts().replaceInstagramPost({ id: 'clx8m2k4p0000a1b2c3d4e5f6', title: 'Example title' });

{
  "title": "",
  "slug": "",
  "_id": "<string>",
  "type": "<string>",
  "caption": "",
  "mediaType": "image",
  "isReel": false,
  "featured": false,
  "visibility": "public",
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "_mediaImage": [
    {}
  ],
  "mediaUrl": "<string>",
  "_video": [
    {}
  ],
  "videoUrl": "<string>",
  "videoRehostStatus": "",
  "permalink": "<string>",
  "postedAt": "2023-12-25",
  "likeCount": 0,
  "commentsCount": 0,
  "comments": [],
  "hiddenComments": [],
  "source": "manual",
  "sourceId": "",
  "archived": false,
  "videoRehostCapBytes": 0,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "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:instagram-posts:write

Path Parameters

_id

string

required

The document’s _id: a full id names its own locale and mode (the draft’s …:en:draft, the published one’s …:en:published; no aposMode needed), a bare aposDocId takes the request’s (aposLocale, aposMode).

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

InstagramPost content type

title

string

default:""

required

Its title: the name it goes by in every list, and the heading of its page where it has one.

slug

string

default:""

required

The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept).

caption

string | null

default:""

The post caption. Shown (optionally truncated) under the image.

mediaType

enum<string> | null

default:image

Drives the corner badge (a video/reel/album marker).

Available options:

image,

video,

carousel,

null

isReel

boolean | null

default:false

Marks a video post as a reel (shows a reel badge instead of a generic video badge).

featured

boolean | null

default:false

Hand-curation flag. The widget can be set to show only featured posts.

visibility

enum<string> | null

default:public

Select whether this content is public or private

Available options:

public,

loginRequired,

null

scheduledPublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

scheduledUnpublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

_mediaImage

Image · object[] | null

The post image (a first-party media-library image). Used for manual posts and for synced posts when “re-host” storage is on. Falls back to the image URL below when empty. The related @apostrophecms/image documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out.

Maximum array length: 1

mediaUrl

string | null

A direct image URL (set by a sync in “hot-link” storage mode). Used only when no library image is set above. Instagram CDN URLs expire — prefer a library image. When set, a URL; empty or null when not.

_video

Video · object[] | null

The playable clip as a first-party file (a piece from the Videos library). Set by a sync when “re-host” video storage is on; also pickable by hand for a manual post. Takes precedence over the video URL below — and, unlike it, never expires and needs no cookie consent to play. The related video documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out.

Maximum array length: 1

videoUrl

string | null

A direct, hot-linked video file URL (set by a sync for video/reel posts under “hot-link” video storage). Played in-place in the on-site lightbox; the still image above is the poster. Instagram CDN video URLs expire quickly (~32h) — the site re-checks freshness and the cron keeps it rotating, and a visitor who has not accepted functional cookies gets the still instead (the file loads from Meta). Re-host the video to avoid both. When set, a URL; empty or null when not.

permalink

string | null

The link to this post on Instagram. The whole tile links here when set. When set, a URL; empty or null when not.

postedAt

string<date> | null

Posted date.

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.

videoRehostCapBytes

integer | null

default:0

With videoRehostStatus: too-large, the size cap (bytes) the clip was over; 0 otherwise. Set by the sync.

Response

Success

InstagramPost content type

title

string

default:""

required

Its title: the name it goes by in every list, and the heading of its page where it has one.

slug

string

default:""

required

The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept).

_id

string

required

read-only

The document’s id. On a type with drafts it ends in its locale and mode (…:en:published, …:en:draft): the part before the first colon is its aposDocId, shared by both copies. The {_id} the type’s routes take.

type

string

required

read-only

The document type’s name: always this type’s.

caption

string | null

default:""

The post caption. Shown (optionally truncated) under the image.

mediaType

enum<string> | null

default:image

Drives the corner badge (a video/reel/album marker).

Available options:

image,

video,

carousel,

null

isReel

boolean | null

default:false

Marks a video post as a reel (shows a reel badge instead of a generic video badge).

featured

boolean | null

default:false

Hand-curation flag. The widget can be set to show only featured posts.

visibility

enum<string> | null

default:public

Select whether this content is public or private

Available options:

public,

loginRequired,

null

scheduledPublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

scheduledUnpublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

_mediaImage

Image · object[] | null

Maximum array length: 1

mediaUrl

string | null

_video

Video · object[] | null

Maximum array length: 1

videoUrl

string | null

videoRehostStatus

enum<string> | null

default:""

read-only

Why this post’s clip is still loading from Instagram instead of your own media library. Anything other than the first value means the video expires in ~32h and is hidden from visitors who declined functional cookies. “Too large” is fixable: raise the cap in Connections → Instagram.

Available options:

too-large,

not-video,

failed,

null

permalink

string | null

The link to this post on Instagram. The whole tile links here when set. When set, a URL; empty or null when not.

postedAt

string<date> | null

Posted date.

likeCount

integer | null

default:0

read-only

Likes.

commentsCount

integer | null

default:0

read-only

Comments count.

comments

Comments · object[] | null

read-only

Comments.

Show child attributes

hiddenComments

Hidden comments · object[] | null

read-only

Hidden comments.

Show child attributes

source

enum<string> | null

default:manual

read-only

Source.

Available options:

manual,

instagram-login,

facebook-login,

demo,

null

sourceId

string | null

default:""

read-only

The Graph media id — the de-duplication key set by a sync.

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.

videoRehostCapBytes

integer | null

default:0

With videoRehostStatus: too-large, the size cap (bytes) the clip was over; 0 otherwise. Set by the sync.

createdAt

string<date-time> | null

read-only

When it was created (ISO 8601).

updatedAt

string<date-time> | null

read-only

When it last changed (ISO 8601).

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/instagram-post/{_id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "",
  "slug": ""
}
'

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

const site = createSiteClient();
const instagramPost = await site.instagramPosts().replaceInstagramPost({ id: 'clx8m2k4p0000a1b2c3d4e5f6', title: 'Example title' });

{
  "title": "",
  "slug": "",
  "_id": "<string>",
  "type": "<string>",
  "caption": "",
  "mediaType": "image",
  "isReel": false,
  "featured": false,
  "visibility": "public",
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "_mediaImage": [
    {}
  ],
  "mediaUrl": "<string>",
  "_video": [
    {}
  ],
  "videoUrl": "<string>",
  "videoRehostStatus": "",
  "permalink": "<string>",
  "postedAt": "2023-12-25",
  "likeCount": 0,
  "commentsCount": 0,
  "comments": [],
  "hiddenComments": [],
  "source": "manual",
  "sourceId": "",
  "archived": false,
  "videoRehostCapBytes": 0,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "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 an Instagram post

Authorizations

Scopes

Path Parameters

Query Parameters

Body

Response