Quickstart

This walks through the shortest path from an API key to a published post: get a key, connect a social account, send a post, and have the owner approve it.

1. Get an API key

Once your workspace is approved, generate a key from the dashboard. Every request uses it as a Bearer token:

Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx

Use an imma_test_ key while you build. Test keys only post to sandbox accounts and never publish publicly.

2. Connect a social account

Your customer (or you, for your own accounts) connects TikTok, Instagram, Facebook Pages or Threads through a hosted link, not through your own OAuth screens.

curl -X POST https://api.getimma.com/v1/connect/links \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "prof_01J...",
    "platforms": ["tiktok", "instagram"]
  }'

The response is { "url": "https://getimma.com/connect/{token}" }. Send that link to the account owner (commonly over Telegram). They log in on each platform's own screen and grant access, nothing is entered on your side.

3. Publish a post

curl -X POST https://api.getimma.com/v1/posts \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9b6c2e-3b9a-4b8a-9b2e-3f9b6c2e3b9a" \
  -d '{
    "profile_id": "prof_01J...",
    "caption": "Rendang 1 kg, pre-order until Friday #rendang",
    "media": ["med_01J..."],
    "targets": [
      { "account_id": "acc_ig_...", "instagram": { "type": "reel" } },
      { "account_id": "acc_tt_...", "tiktok": { "mode": "direct" } }
    ],
    "scheduled_at": "2026-09-28T18:30:00+07:00",
    "approval": { "mode": "link", "notify": { "email": "[email protected]" } },
    "ai_generated": true
  }'

Response (201):

{
  "id": "post_01J...",
  "status": "awaiting_approval",
  "approval": {
    "id": "apr_...",
    "url": "https://getimma.com/approve/k8Fq2...",
    "expires_at": "..."
  },
  "targets": [
    { "id": "tgt_1", "account_id": "acc_ig_...", "status": "awaiting_approval" },
    { "id": "tgt_2", "account_id": "acc_tt_...", "status": "awaiting_approval" }
  ],
  "warnings": []
}

Always send an Idempotency-Key. If the request times out and you retry with the same key and body, you get back the original result instead of a duplicate post.

4. Get the post approved

Because approval.mode is "link", every target (including TikTok) waits for a human. Send the approval.url to the account owner. They see the exact caption, media and thumbnail, and for TikTok they pick a privacy option themselves; IMMA AI never preselects one. See Platform rules for why this step cannot be skipped for TikTok.

Once approved, GET /v1/posts/{id} shows each target moving to scheduled, then publishing, then published with the live permalink.

Next steps

• Concepts: what a profile, account, post, target and approval mean in the API.
• Authentication: key types, scopes, and multi-tenant profiles.
• Platform rules: TikTok consent and Meta/TikTok posting limits.
• MCP quickstart: the same flow, but driven by an AI agent instead of your own code.