Quickstart

Go from zero to a published (mock) post in under five minutes, entirely in sandbox mode. No Meta, TikTok, or X developer account required.

1. Create a workspace

Sign up at omnipost.dev/signup and create a workspace. Every API key, connected account, and post you create belongs to a workspace.

2. Generate a sandbox API key

From your workspace dashboard, go to Settings → API Keys and create a new key in Sandbox mode. Copy it now — the full value is only shown once.

op_sandbox_51H8x9K2mZqP7vNtR3wYbL6cJdXsAeUf

Store it as an environment variable rather than pasting it into your code. All examples below read it from OMNIPOST_API_KEY.

export OMNIPOST_API_KEY="op_sandbox_51H8x9K2mZqP7vNtR3wYbL6cJdXsAeUf"

Every post needs at least one connected account per target platform. Request a hosted connect URL for Instagram:

curl -X POST https://api.omnipost.dev/v1/accounts/instagram/connect \
  -H "Authorization: Bearer $OMNIPOST_API_KEY"

Because you're using a sandbox key, the returned urlpoints to OmniPost's hosted mockconnect screen instead of the real Instagram OAuth consent screen. Open it, click "Connect", and OmniPost creates a fake but fully functional Instagram account (status: active) in your workspace — no Instagram login involved. See Connecting Accounts for the production flow.

4. Publish a post

Call POST /v1/upload with a caption, media URL, and target platform. Because the key is sandbox-mode, this does not call Instagram — it queues a deterministic mock publish.

curl -X POST https://api.omnipost.dev/v1/upload \
  -H "Authorization: Bearer $OMNIPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Hello from the OmniPost quickstart!",
    "media": [{ "url": "https://picsum.photos/1080/1080", "type": "image" }],
    "platforms": ["instagram"]
  }'

OmniPost responds immediately with a pending post:

{
  "id": "post_8f3d1a9c2b7e4f01",
  "status": "pending",
  "targets": [
    { "platform": "instagram", "status": "pending" }
  ]
}

5. Check status

Poll GET /v1/posts/:id — in sandbox mode targets resolve to published a couple of seconds after creation, with a mock external_url.

curl https://api.omnipost.dev/v1/posts/post_8f3d1a9c2b7e4f01 \
  -H "Authorization: Bearer $OMNIPOST_API_KEY"

{
  "id": "post_8f3d1a9c2b7e4f01",
  "status": "completed",
  "caption": "Hello from the OmniPost quickstart!",
  "created_at": "2026-08-02T14:03:11Z",
  "targets": [
    {
      "platform": "instagram",
      "status": "published",
      "external_url": "https://sandbox.omnipost.dev/mock/instagram/post_8f3d1a9c2b7e4f01",
      "published_at": "2026-08-02T14:03:13Z"
    }
  ]
}

That's it

You just ran the full publish lifecycle without a single real platform credential. Swap the op_sandbox_ key for an op_live_ key once your platform app reviews are approved and real accounts are connected — the request and response shapes don't change. Continue with Authentication or dive into Sandbox Mode to learn how to simulate failures for testing.

What's next