Quickstart

This guide walks you from a fresh account to a live post on Instagram and Facebook.

1. Get an API key

export MADIAD_API_KEY="mdc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Treat API keys like passwords. Do not commit them to git or expose them in client-side code.

2. Connect a profile

A profile represents a brand, client, or sub-account that you publish on behalf of. Create one and connect the social platforms you want to publish to.

curl -X POST https://api.madiad.com/v1/connections/start \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "friendly_name": "Acme Coffee" }'

Response:

{
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "friendly_name": "Acme Coffee",
  "access_url": "https://connect.madiad.com/o/abc123def456",
  "expires_in": "48h"
}

Open access_url in a browser and sign in to each social platform you want to publish to (Instagram, Facebook, TikTok, etc.). Connections persist until revoked.

3. Publish to multiple platforms

Send a single request — the Hub fans it out.

curl -X POST https://api.madiad.com/v1/posts/photos \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Idempotency-Key: launch-2026-05-31-001" \
  -F "profile_id=prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z" \
  -F "platforms[]=instagram" \
  -F "platforms[]=facebook" \
  -F "caption=New blend dropping today" \
  -F "photos[]=@./launch.jpg"

Response:

{
  "status": "completed",
  "profile_id": "prof_01HZX9F2K4M7N6QR8T0V2W4Y6Z",
  "platforms": ["instagram", "facebook"],
  "request_id": null,
  "job_id": null,
  "results": {
    "instagram": { "success": true, "publish_id": "17912345678901234", "url": "https://instagram.com/p/abc123" },
    "facebook":  { "success": true, "publish_id": "12345_67890", "url": "https://facebook.com/12345/posts/67890" }
  }
}

A video (or any asynchronous upload) instead returns "status": "processing" with a request_id to poll. See Posts for every status value.

4. (Optional) Schedule for later

Replace the immediate publish with a future timestamp.

-F "scheduled_at=2026-06-01T15:00:00Z" \
-F "timezone=Asia/Ho_Chi_Minh"

Get notified when uploads finish or a connection changes, instead of polling. Create an endpoint from your dashboard at hub.madiad.com/dashboard/webhooks — set the URL to receive deliveries and pick the events (post.completed, connection.connected, connection.disconnected, connection.reauth_required). The Hub signs every callback with HMAC-SHA256. See Webhooks for verification.

Next steps

Profile model

How profiles work across brands and clients.

Per-platform fields

Override captions, thumbnails, and visibility per platform.

Scheduling

Exact times vs. recurring queue slots.

Idempotency

Make safe retries from any client.

Get Started

Concepts

Integrations

1. Get an API key

2. Connect a profile

3. Publish to multiple platforms

4. (Optional) Schedule for later

Next steps

Profile model

Per-platform fields

Scheduling

Idempotency

​1. Get an API key

​2. Connect a profile

​3. Publish to multiple platforms

​4. (Optional) Schedule for later

​5. (Optional) Subscribe to webhooks

​Next steps

Profile model

Per-platform fields

Scheduling

Idempotency

1. Get an API key

2. Connect a profile

3. Publish to multiple platforms

4. (Optional) Schedule for later

5. (Optional) Subscribe to webhooks

Next steps