Concepts

Six objects cover everything in the IMMA AI API. Once these are clear, the rest of the reference is mostly which fields each endpoint accepts.

Workspace

The account you or your agency signs up with. Holds billing, team members and API keys. Workspaces are strictly isolated: nothing in one workspace is ever visible to another.

Profile

A profile represents one end customer inside your workspace, for example one of your agency's clients or one UMKM using your product. If you only manage your own social accounts, you still have a single default profile. Most API calls take a profile_id (prof_...) so a multi-tenant integration can keep customers separate, and the IMMA-Profile header can scope a whole request to one profile.

Account

A connected social account: one TikTok creator account, one Instagram Business account, one Facebook Page, or one Threads account (acc_...). Created by sending someone through a hosted connect link, never by IMMA AI holding credentials on their behalf. Each account exposes its own capabilities, for example a TikTok account's allowed privacy options and maximum video length.

Post

A single piece of content (post_...): a caption plus media, sent to one or more targets. A post has a lifecycle: awaiting_approval (or scheduled/queued if no approval is required), then publishing, then published per target, or failed with a normalized error. POST /posts/batch creates up to 31 posts in one call, each with its own independent status, for building a month of content at once.

Target

One destination for a post: a specific account plus platform specific options, for example { "account_id": "acc_tt_...", "tiktok": { "mode": "direct" } }. A single post can have multiple targets (posting the same content to Instagram and TikTok at once), and each target tracks its own status and error independently, so one platform failing does not affect the others.

Approval

The human checkpoint before a post (or a TikTok target specifically) goes live. approval.mode: "link" generates a hosted page where the account owner reviews the exact content and, for TikTok, picks a privacy option themselves. approval.mode: "none" skips this for non-TikTok targets, but a direct TikTok post without approval still requires an explicit consent object in the request, see Platform rules. Approvals are commonly shared over Telegram as a link.

How they fit together

Workspace
  └─ Profile (one per end customer)
       ├─ Account (one per connected TikTok/Instagram/Facebook/Threads account)
       └─ Post
            ├─ Target (one per account the post goes to)
            └─ Approval (one per post, required before a TikTok target can publish)

Next: Authentication for how workspaces, keys and scopes work together, or jump straight to the Quickstart.