# Quickstart: Publish Your First Post

import { TechArticle } from "../components/TechArticle";

<TechArticle slug="introduction" fm={frontmatter} />

OmniSocials is an API for scheduling and publishing social media posts across 12 channels (11 platforms, with LinkedIn split into a personal profile and a company page) from a single endpoint. This guide gets you from zero to your first published post in five steps, in about five minutes.

You need an [OmniSocials account](https://app.omnisocials.com) and one social account connected to it. Connecting happens once, through OAuth in the dashboard (step 3); it cannot be done through the API.

## 1. Create an API key

Sign in to [app.omnisocials.com](https://app.omnisocials.com), open **Settings → API**, and click **Create API Key**.

Pick the scopes your integration needs. For most use cases, start with `posts:write`, `media:write`, and `accounts:read`. You can add more later.

The key is shown once. Copy it and store it somewhere safe. Keys start with `omsk_live_` (production) or `omsk_test_` (test mode).

```bash
export OMNISOCIALS_API_KEY="omsk_live_<YOUR_KEY>"
```

## 2. Verify access

Every request authenticates with a Bearer token in the `Authorization` header. The easiest way to check the key works is to list your connected accounts.

```bash
curl https://api.omnisocials.com/v1/accounts \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
```

A `200` response with a `data` array (plus `workspace_id` and `workspace_name`) means you're in. If you see `401`, the key is wrong. If you see `403`, the key is missing the `accounts:read` scope.

## 3. Connect a social account

You cannot connect social accounts through the API. Accounts are connected once through OAuth in the OmniSocials dashboard, and then become available to every API key in the workspace.

Open **Settings → Channels**, pick the platform you want, and complete the OAuth flow. Re-run the `GET /accounts` call from step 2 to confirm the account appears in the list. Copy its `id` for the next step.

## 4. Upload media (optional)

Text-only posts skip this step. Platforms that require media (Instagram, TikTok, Pinterest, stories, reels) need a media file or URL.

```bash
curl -X POST https://api.omnisocials.com/v1/media/upload \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -F "file=@photo.jpg"
```

Response:

```json
{
  "data": { "id": "123", "url": "https://cdn.omnisocials.com/...", "type": "image", "status": "ready" },
  "compatibility": { "overall": "ok", "platforms": {} },
  "message": "File uploaded successfully. Use the 'id' in your post request."
}
```

Save `data.id` for the next step.

Alternatively, skip the upload step entirely and pass external URLs directly in `media_urls` on the post. The API downloads and attaches them for you. See [Media](/media) for the full reference.

## 5. Create your first post

Use the account `id` from step 3 and, optionally, the media `id` from step 4.

```bash
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "default": "Hello from the OmniSocials API" },
    "accounts": ["your-account-id"],
    "media": ["123"]
  }'
```

A successful response is a `201` with the new post record:

```json
{
  "data": {
    "id": "1024",
    "status": "draft",
    "content": { "default": "Hello from the OmniSocials API" },
    "accounts": ["instagram"],
    "created_at": "2026-08-20T09:15:00Z"
  }
}
```

The post is saved as a draft. To publish immediately instead, add `"publish_now": true` to the body above, or POST to `/v1/posts/:id/publish` afterwards. `/v1/posts/create-and-publish` is an equivalent alias for the `publish_now` variant. After publishing, poll `GET /v1/posts/1024` until `status` is `published`; the live links appear in `published_urls`.

If the call fails: `401` means the key is wrong, `403` means a missing scope, and `400` returns an `error.message` that names the exact problem. See [Rate limits and errors](/rate-limits-and-errors).

## Next steps

- [SDKs](/sdks) wrap this API in 8 languages (Node, Python, Go, Ruby, PHP, Java, .NET, Rust) so you skip the raw HTTP
- [Creating posts](/creating-posts) covers scheduling, per-platform content, post types, and updates
- [Cross-posting](/cross-posting) covers publishing the same post to many platforms at once (the reason to use OmniSocials instead of calling every platform's API directly)
- [Media](/media) covers upload methods, formats, and size limits
- [Platforms](/platforms) lists channel IDs and platform-specific options
- [Rate limits and errors](/rate-limits-and-errors) lists the limits and status codes you need to handle
- [API reference](/api) is the full endpoint spec generated from the OpenAPI schema