# socialfanout.com API Reference

socialfanout.com is an API-first social publishing service for apps, automations, and AI agents. It exposes a hosted REST API plus a local stdio MCP server over that REST API.

Base URL: `https://socialfanout.com`

## Authentication

Send one API key per request:

```http
x-api-key: spk_...
```

or:

```http
Authorization: Bearer spk_...
```

API keys are scoped to their own plan limits and are stored hashed at rest.

## Health

```http
GET /health
GET /health/ready
```

Returns service liveness and sanitized runtime readiness for uptime checks.

## Providers

```http
GET /v1/providers
```

Returns provider registry entries and capability metadata. Use registry data and connection status instead of assuming every destination is available.

## Connections

```http
GET /v1/connections
POST /v1/connections/oauth/start
```

Connections represent authorized provider accounts for the API key or signed-in dashboard user. OAuth availability depends on provider configuration, review status, and account permissions.

## Publish

```http
POST /v1/publish
Content-Type: application/json
x-api-key: spk_...
```

Example request:

```json
{
  "accountId": "conn_...",
  "platform": "bluesky",
  "connectionId": "conn_...",
  "text": "socialfanout.com gives agents one API for connected social publishing.",
  "mediaUrls": []
}
```

The v1 publish endpoint accepts one destination per request. For fan-out, issue one request for each connected account you want to publish to.

The response creates a publishing job and records provider results. Destination failures should include safe diagnostic context without exposing secrets.

## Jobs and Posts

```http
GET /v1/jobs
GET /v1/posts
```

Use these endpoints to inspect queued, completed, and failed publishing work.

## Billing

```http
POST /v1/billing/checkout
POST /v1/billing/provision
```

Stripe checkout provisions paid API keys. Signed-in dashboard users can attach checkout-provisioned keys to their dashboard account.

## MCP

socialfanout.com MCP access is local stdio over the REST API, not a hosted remote MCP endpoint.

```bash
FANOUT_API_KEY=spk_... npm run mcp
```

The MCP server exposes agent-friendly tools for health, provider discovery, connections, OAuth start, and publishing.

## Provider Availability

Public integrations should say: socialfanout.com publishes to connected and approved destinations. Availability depends on provider approval, OAuth scopes, account permissions, and upstream provider health.

TikTok and Pinterest production publishing are approval-gated until production sign-off and smoke tests are confirmed.