# Social Media API SDKs in 8 Languages

Official client libraries for the OmniSocials API in 8 languages. Every SDK has the
same shape: resource-based clients (`client.posts.create(...)`), typed requests and
responses, automatic retries with backoff, a shared error hierarchy, and a webhook
signature verification helper. Pick your language and you are posting in five lines.

## Install

Each language has its own page with full examples: install, auth, posting, media,
analytics, webhooks, and error handling.

| Language | Package | Install | Docs |
|----------|---------|---------|------|
| Node.js / TypeScript | `@omnisocials/sdk` | `npm install @omnisocials/sdk` | [Node.js](/sdks/node) |
| Python | `omnisocials` | `pip install omnisocials` | [Python](/sdks/python) |
| Go | `github.com/OmniSocials/omnisocials-go` | `go get github.com/OmniSocials/omnisocials-go` | [Go](/sdks/go) |
| Ruby | `omnisocials` | `gem install omnisocials` | [Ruby](/sdks/ruby) |
| Java | `com.omnisocials:omnisocials-java` | Maven / Gradle dependency | [Java](/sdks/java) |
| PHP | `omnisocials/omnisocials-php` | `composer require omnisocials/omnisocials-php` | [PHP](/sdks/php) |
| .NET | `OmniSocials` | `dotnet add package OmniSocials` | [.NET](/sdks/dotnet) |
| Rust | `omnisocials` | `cargo add omnisocials` | [Rust](/sdks/rust) |

All 8 cover the full v1 surface: posts (including create-and-publish, per-platform
options, and X / Bluesky / Mastodon threads), media (URL, base64, multipart, PDF
carousels, presigned large-file uploads), folders, hashtag sets (CRUD plus applying
a set at post create via `hashtag_set` / `hashtag_placement`), accounts, analytics
(post, bulk, overview, accounts, best times), Instagram locations, Instagram Reel
music search, and webhooks (CRUD plus secret rotation and signature verification).

## Authentication

Every SDK reads the `OMNISOCIALS_API_KEY` environment variable, or takes the key in
the constructor. Create a key in the OmniSocials app under **Settings -> API**. Keys
start with `omsk_live_` (production) or `omsk_test_` (test mode).

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

## Quickstart

### Node.js / TypeScript

```ts
import { OmniSocials } from "@omnisocials/sdk";

const client = new OmniSocials(); // reads OMNISOCIALS_API_KEY from env
const post = await client.posts.create({
  content: "Hello from the SDK",
  channels: ["instagram", "linkedin"],
  scheduled_at: "2026-08-01T09:00:00Z",
});
```

### Python

```python
from omnisocials import OmniSocials

client = OmniSocials()  # reads OMNISOCIALS_API_KEY from the environment
post = client.posts.create(content="Hello from Python", channels=["instagram", "linkedin"])
print(post["data"]["id"])
```

A synchronous and an async client (`AsyncOmniSocials`) ship in the Python package.
The Go, Ruby, PHP, Java, .NET, and Rust clients expose the same resources and methods
adapted to each language's idiom. Full runnable examples for every resource live in
each package's README (linked in the table above).

## Configuration

Every client accepts the same options: `apiKey`, `baseUrl`, `timeout` (default 30s),
and `maxRetries` (default 2). Retries use exponential backoff with jitter on `429`,
`5xx`, and network errors, and honor the `Retry-After` header. Other `4xx` responses
are never retried.

## Errors

Non-2xx responses raise a typed error from a shared hierarchy: a base error, an API
error carrying `status` / `code` / `body`, and per-status subclasses (authentication,
permission, not-found, validation, rate-limit with `retry_after`, server), plus a
connection error and a webhook-verification error. See
[Rate limits and errors](/rate-limits-and-errors) for the status codes.

## Webhook verification

Each SDK ships a helper that verifies the `X-OmniSocials-Signature` header (HMAC-SHA256
over `"{timestamp}.{rawBody}"`, constant-time compare, replay-window check) and returns
the parsed event. Node example:

```ts
import { verifyWebhookSignature } from "@omnisocials/sdk";

app.post("/webhooks/omnisocials", express.raw({ type: "application/json" }), (req, res) => {
  const event = verifyWebhookSignature({
    payload: req.body, // raw bytes, not parsed JSON
    signature: req.header("X-OmniSocials-Signature"),
    secret: process.env.OMNISOCIALS_WEBHOOK_SECRET,
  });
  // handle event.type ...
  res.sendStatus(200);
});
```

See [Webhooks](/webhooks) for event types and payloads.

## Prefer a different integration?

- [MCP Server](/mcp-server) for AI assistants (Claude, ChatGPT, Cursor, and more)
- [Agent Skills](/integrations/agent-skills) for AI coding tools without MCP support
- [API Reference](/api) for the raw HTTP endpoints