Create an Instagram post

import app from '@adonisjs/core/services/app'
import { SiteClient } from '@fetchski/attract-cms-sdk'

const site = await app.container.make(SiteClient)
const instagramPost = await site.instagramPosts().createInstagramPost({ title: 'Example title' })

{
  "title": "Example title",
  "caption": "Example caption",
  "mediaType": "image",
  "isReel": false,
  "featured": false,
  "slug": "example-slug",
  "visibility": "public",
  "scheduledPublish": "Example scheduled publish",
  "scheduledUnpublish": "Example scheduled unpublish",
  "_mediaImage": [
    {}
  ],
  "mediaUrl": "https://acme.example/example",
  "_video": [
    {}
  ],
  "videoUrl": "https://acme.example/example",
  "videoRehostStatus": "",
  "permalink": "https://acme.example/example",
  "postedAt": "2026-10-24",
  "likeCount": 0,
  "commentsCount": 0,
  "comments": [],
  "hiddenComments": [],
  "source": "manual",
  "sourceId": "clx8m2k4p0000a1b2c3d4e5f6",
  "archived": false,
  "videoRehostCapBytes": 0,
  "_id": "clx8m2k4p0000a1b2c3d4e5f6",
  "type": "Example type",
  "createdAt": "2026-10-24T09:30:00.000Z",
  "updatedAt": "2026-10-24T09:30:00.000Z",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

import app from '@adonisjs/core/services/app'
import { SiteClient } from '@fetchski/attract-cms-sdk'

const site = await app.container.make(SiteClient)
const instagramPost = await site.instagramPosts().createInstagramPost({ title: 'Example title' })

{
  "title": "Example title",
  "caption": "Example caption",
  "mediaType": "image",
  "isReel": false,
  "featured": false,
  "slug": "example-slug",
  "visibility": "public",
  "scheduledPublish": "Example scheduled publish",
  "scheduledUnpublish": "Example scheduled unpublish",
  "_mediaImage": [
    {}
  ],
  "mediaUrl": "https://acme.example/example",
  "_video": [
    {}
  ],
  "videoUrl": "https://acme.example/example",
  "videoRehostStatus": "",
  "permalink": "https://acme.example/example",
  "postedAt": "2026-10-24",
  "likeCount": 0,
  "commentsCount": 0,
  "comments": [],
  "hiddenComments": [],
  "source": "manual",
  "sourceId": "clx8m2k4p0000a1b2c3d4e5f6",
  "archived": false,
  "videoRehostCapBytes": 0,
  "_id": "clx8m2k4p0000a1b2c3d4e5f6",
  "type": "Example type",
  "createdAt": "2026-10-24T09:30:00.000Z",
  "updatedAt": "2026-10-24T09:30:00.000Z",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

In your app

A controller answers a route on your app: it calls createInstagramPost() and returns the answer.

Add the controller

app/controllers/create_instagram_post_controller.ts

import { inject } from '@adonisjs/core'
import { SiteClient } from '@fetchski/attract-cms-sdk'

@inject()
export default class CreateInstagramPostController {
  constructor(protected site: SiteClient) {}

  async handle() {
    return this.site.instagramPosts().createInstagramPost({ title: 'Example title' })
  }
}

The other values are the example’s: take yours from the request, a form or your database.

Add the route

start/routes.ts

import router from '@adonisjs/core/services/router'

const CreateInstagramPostController = () => import('#controllers/create_instagram_post_controller')

router.post('/instagram-post', [CreateInstagramPostController])

Put it behind your auth middleware (.use(middleware.auth())): it acts with your key’s access.

Call it

Your own page’s form or script sends POST /instagram-post and gets back its answer as JSON. Test it, below, calls it.

Required parameters

One object, e.g. createInstagramPost({ title }); leave out the optional fields.

string

required

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

Optional parameters

AposMode | null | undefined

Optional. Leave it out and the site uses "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. One of draft, published.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. The locale to read or write, e.g. en (default: the site’s default locale).

string | null | undefined

Optional. Leave it out and the site uses "". The post caption. Shown (optionally truncated) under the image.

MediaType | null | undefined

Optional. Leave it out and the site uses "image". Drives the corner badge (a video/reel/album marker). One of image, video, carousel.

boolean | null | undefined

Optional. Leave it out and the site uses false. Marks a video post as a reel (shows a reel badge instead of a generic video badge).

boolean | null | undefined

Optional. Leave it out and the site uses false. Hand-curation flag. The widget can be set to show only featured posts.

string | null | undefined

Optional. Leave it out and the site uses "". The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept). Left out, it’s made from the title.

Visibility | null | undefined

Optional. Leave it out and the site uses "public". Select whether this content is public or private. One of public, loginRequired.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

readonly Readonly<Record<string, unknown>>[] | null | undefined

Optional. 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. At most 1 items.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. 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.

readonly Readonly<Record<string, unknown>>[] | null | undefined

Optional. 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. At most 1 items.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. 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.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. The link to this post on Instagram. The whole tile links here when set. When set, a URL; empty or null when not.

Date | string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Posted date. Format: an ISO 8601 date (YYYY-MM-DD).

boolean | null | undefined

Optional. Leave it out and the site uses 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.

number | null | undefined

Optional. Leave it out and the site uses 0. With videoRehostStatus: too-large, the size cap (bytes) the clip was over; 0 otherwise. Set by the sync.

Returns

An InstagramPost. InstagramPost content type. Read its properties (instagramPost.title): each says whether the site always sends it. The example answer is the site’s wire JSON: some keys differ from the property names (_id → id, _mediaImage → mediaImage, _video → video).

string

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

string

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

string

Always sent. 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.

string

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

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The post caption. Shown (optionally truncated) under the image.

MediaType | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Drives the corner badge (a video/reel/album marker). One of image, video, carousel; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Marks a video post as a reel (shows a reel badge instead of a generic video badge).

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Hand-curation flag. The widget can be set to show only featured posts.

Visibility | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Select whether this content is public or private. One of public, loginRequired; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

readonly Readonly<Record<string, unknown>>[] | null

Sometimes sent: undefined when the site leaves it out, and it can be 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. At most 1 items.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be 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.

readonly Readonly<Record<string, unknown>>[] | null

Sometimes sent: undefined when the site leaves it out, and it can be 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. At most 1 items.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be 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.

VideoRehostStatus | null

Sometimes sent: undefined when the site leaves it out, and it can be null. 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. One of “, too-large, not-video, failed; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The link to this post on Instagram. The whole tile links here when set. When set, a URL; empty or null when not.

Date | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Posted date. Format: an ISO 8601 date (YYYY-MM-DD).

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Likes.

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Comments count.

readonly InstagramPostCommentsItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of InstagramPostCommentsItem. Comments.

Show InstagramPostCommentsItem

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

string

Sometimes sent: undefined when the site leaves it out. Comment.

string

Sometimes sent: undefined when the site leaves it out. Author.

string

Sometimes sent: undefined when the site leaves it out. Author ID (IGSID).

string

Sometimes sent: undefined when the site leaves it out. Parent comment ID.

string

Sometimes sent: undefined when the site leaves it out. Posted at.

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Likes.

Readonly<Record<string, unknown>>

Always there: {} when there are none. Any keys the site sent that aren’t listed above (such as one added after this SDK was built), by their wire names, as sent. Pass this model to a write and they are sent too.

readonly InstagramPostHiddenCommentsItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of InstagramPostHiddenCommentsItem. Hidden comments.

Show InstagramPostHiddenCommentsItem

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

string

Sometimes sent: undefined when the site leaves it out. Comment.

string

Sometimes sent: undefined when the site leaves it out. Author.

string

Sometimes sent: undefined when the site leaves it out. Author ID (IGSID).

string

Sometimes sent: undefined when the site leaves it out. Parent comment ID.

string

Sometimes sent: undefined when the site leaves it out. Posted at.

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Likes.

Readonly<Record<string, unknown>>

InstagramPostSource | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Source. One of manual, instagram-login, facebook-login, demo; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The Graph media id — the de-duplication key set by a sync.

boolean | null

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

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. With videoRehostStatus: too-large, the size cap (bytes) the clip was over; 0 otherwise. Set by the sync.

Date | null

Sometimes sent: undefined when the site leaves it out, and it can be null. When it was created (ISO 8601). Format: an ISO 8601 date and time.

Date | null

Sometimes sent: undefined when the site leaves it out, and it can be null. When it last changed (ISO 8601). Format: an ISO 8601 date and time.

Sometimes sent: undefined when the site leaves it out, and it can be null. 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.

Errors

Nothing to catch: the SDK retries what is safe, and throws the rest as the classes below. Your exception handler turns them into your app’s own answers, once for every call (see Map SDK errors to responses); catch only what you want to react to here.

400

The site refused what was sent: errors lists each field’s problem, siteMessage the first.Retried first: No. Read: errors (field → messages), siteMessage.

401

The API key is missing or refused (malformed, revoked, expired), or a signature its signing mode needs is missing or stale.Retried first: No. Read: siteMessage, errorName, data.

403

The key may not do this: a scope it lacks, or an address outside its allowlist. siteMessage names it.Retried first: No. Read: siteMessage, errorName, data.

404

Nothing matches, or the caller may not see it.Retried first: No. Read: siteMessage, errorName, data.

500

The site failed. Its logs say why.Retried first: No: a write may have landed. Read: siteMessage, errorName, data.

no answer

No answer: DNS, a refused connection, TLS, or the timeout (15 s per attempt by default).Retried first: Only when nothing reached the site (neverConnected()); never after a timeout, when it may have landed. Read: reason, neverConnected.

not sent

The client refused to send it (e.g. a path segment of ..); the site never saw it.Retried first: No. Read: reason (what to change).

any other

Any other status, or a success whose JSON doesn’t match this SDK version’s types (update the SDK).Retried first: No. Read: reason, status.

setup

sites.forSite('acme') named a slug config/attract.ts doesn’t list (with the keys in the database: no row in attract_api_keys).Retried first: No: nothing was sent. Read: message, slug.

setup

The site’s entry is wrong: a malformed baseUrl or key, a key filed under another slug, or no default site. node ace attract:check names the fix.Retried first: No: nothing was sent. Read: message (what to fix).

Behavior

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 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. The client waits and retries for you; you see RateLimited only if that runs out.
Retries: a write is sent again only after a 429 (refused before it acted) or when it never reached the site. After a timeout or a 5xx it may have landed: check before you send it again.
Timeout: 15 s per attempt by default; raise timeout (milliseconds) in config/attract.ts for longer.

Test it

It calls the controller above with the SDK faked: fakeAttract() puts the fake in the container for this one test, and it answers every call with a valid example, so nothing leaves your machine and no key is read. Save it as tests/unit/instagram_posts_create_instagram_post.spec.ts, then run your tests:

tests/unit/instagram_posts_create_instagram_post.spec.ts

import { test } from '@japa/runner'
import app from '@adonisjs/core/services/app'
import { fakeAttract } from '@fetchski/attract-cms-adonis/testing'
import CreateInstagramPostController from '#controllers/create_instagram_post_controller'

test('instagramPosts.createInstagramPost', async () => {
  const site = fakeAttract()

  const controller = await app.container.make(CreateInstagramPostController)
  await controller.handle()

  site.assertCalled('instagramPosts.createInstagramPost')
})

Terminal

node ace test

Answer with your own values: fake instagramPosts.createInstagramPost with factories.InstagramPost({...}), the fields you give over a valid example.

tests/unit/instagram_posts_create_instagram_post_answers.spec.ts

import { test } from '@japa/runner'
import { factories, fakeAttract } from '@fetchski/attract-cms-adonis/testing'

test('instagramPosts.createInstagramPost answers your values', async ({ assert }) => {
  const site = fakeAttract({
    'instagramPosts.createInstagramPost': factories.InstagramPost({ title: 'Your value' }),
  })

  const instagramPost = await site.instagramPosts().createInstagramPost({ title: 'Example title' })
  assert.containSubset(instagramPost, { title: 'Your value' })
})

List an Instagram post’s locales

site.instagramPosts().getInstagramPostLocales()

List Instagram posts

site.instagramPosts().listInstagramPosts()

Get an Instagram post

site.instagramPosts().getInstagramPost()

Replace an Instagram post

site.instagramPosts().replaceInstagramPost()

Delete an Instagram post

site.instagramPosts().deleteInstagramPost()

Update an Instagram post

site.instagramPosts().updateInstagramPost()

POST /instagram-post

The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.

import app from '@adonisjs/core/services/app'
import { SiteClient } from '@fetchski/attract-cms-sdk'

const site = await app.container.make(SiteClient)
const instagramPost = await site.instagramPosts().createInstagramPost({ title: 'Example title' })

{
  "title": "Example title",
  "caption": "Example caption",
  "mediaType": "image",
  "isReel": false,
  "featured": false,
  "slug": "example-slug",
  "visibility": "public",
  "scheduledPublish": "Example scheduled publish",
  "scheduledUnpublish": "Example scheduled unpublish",
  "_mediaImage": [
    {}
  ],
  "mediaUrl": "https://acme.example/example",
  "_video": [
    {}
  ],
  "videoUrl": "https://acme.example/example",
  "videoRehostStatus": "",
  "permalink": "https://acme.example/example",
  "postedAt": "2026-10-24",
  "likeCount": 0,
  "commentsCount": 0,
  "comments": [],
  "hiddenComments": [],
  "source": "manual",
  "sourceId": "clx8m2k4p0000a1b2c3d4e5f6",
  "archived": false,
  "videoRehostCapBytes": 0,
  "_id": "clx8m2k4p0000a1b2c3d4e5f6",
  "type": "Example type",
  "createdAt": "2026-10-24T09:30:00.000Z",
  "updatedAt": "2026-10-24T09:30:00.000Z",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

Get started

Using the SDK

Going further

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

In your app

Behavior

Test it

List an Instagram post’s locales

List Instagram posts

Get an Instagram post

Replace an Instagram post

Delete an Instagram post

Update an Instagram post

POST /instagram-post

In your app

Behavior

Test it

Related

List an Instagram post’s locales

List Instagram posts

Get an Instagram post

Replace an Instagram post

Delete an Instagram post

Update an Instagram post

POST /instagram-post