Developer Platform

Build with FluxSocial

A versioned REST API, an MCP server for AI tools, and API key management. Generate content, post to platforms, and manage credits programmatically.

REST API Reference MCP Server Setup

REST endpoints

MCP tools

fsx_live_

Key prefix

SHA-256

Key hashing

Getting Started

1. Create an API Key

2. Authenticate

Pass your API key as a Bearer token in the Authorization header.

Authentication

bash

curl https://www.fluxsocial.app/api/v1/credits/balance \
  -H "Authorization: Bearer fsx_live_YOUR_KEY"

3. Generate Content

Generate content with a single POST. Credits are deducted from your balance (same pool as the web app).

POST /api/v1/content

bash

curl -X POST https://www.fluxsocial.app/api/v1/content \
  -H "Authorization: Bearer fsx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Morning yoga tips for beginners",
    "businessId": "biz_...",
    "contentFormat": "IMAGE"
  }'

Response

json

{
  "sessionId": "ses_...",
  "suggestions": [
    {
      "id": "sug_...",
      "title": "5 Morning Yoga Poses",
      "body": "Start your day with intention...",
      "contentFormat": "IMAGE",
      "tags": ["yoga", "wellness", "morning"]
    }
  ],
  "creditsUsed": 20,
  "balanceAfter": 4980
}

Workflows

Complete REST Workflow

End-to-end examples showing how endpoints chain together.

Flow A — Generate & Post

Step 1 — Get your business ID

GET /api/v1/businesses

bash

curl https://www.fluxsocial.app/api/v1/businesses \
  -H "Authorization: Bearer fsx_live_YOUR_KEY"

Response

json

{
  "businesses": [
    { "id": "biz_abc123", "name": "The Morning Cup" }
  ]
}

Step 2 — Generate content

POST /api/v1/content

bash

curl -X POST https://www.fluxsocial.app/api/v1/content \
  -H "Authorization: Bearer fsx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Morning latte art", "businessId": "biz_abc123", "contentFormat": "IMAGE" }'

Response

json

{
  "sessionId": "ses_xyz",
  "suggestions": [{ "id": "sug_001", "title": "Latte Art Magic", "body": "..." }],
  "creditsUsed": 20
}

Step 3 — Generate an image

POST /api/v1/content/sug_001/image

bash

curl -X POST https://www.fluxsocial.app/api/v1/content/sug_001/image \
  -H "Authorization: Bearer fsx_live_YOUR_KEY"

Response

json

{ "imageUrl": "https://...", "creditsUsed": 50 }

Step 4 — Post to Instagram

POST /api/v1/content/sug_001/post

bash

curl -X POST https://www.fluxsocial.app/api/v1/content/sug_001/post \
  -H "Authorization: Bearer fsx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targets": [{ "accountId": "acc_ig1", "platform": "instagram" }] }'

Response

json

{
  "suggestionId": "sug_001",
  "results": [{ "platform": "instagram", "status": "success", "postUrl": "https://instagram.com/p/..." }]
}

Flow B — Schedule for Later

Step 1 — Get optimal posting time

GET /api/v1/schedule/optimal-time

bash

curl "https://www.fluxsocial.app/api/v1/schedule/optimal-time?businessId=biz_abc123" \
  -H "Authorization: Bearer fsx_live_YOUR_KEY"

Response

json

{
  "success": true,
  "data": {
    "scheduledDateTime": "2026-04-09T09:30:00.000Z",
    "confidence": 0.87,
    "reasoning": "Highest engagement for your audience on Wednesday mornings"
  }
}

Step 2 — Schedule the post

POST /api/v1/content/sug_001/schedule

bash

curl -X POST https://www.fluxsocial.app/api/v1/content/sug_001/schedule \
  -H "Authorization: Bearer fsx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledFor": "2026-04-09T09:30:00.000Z",
    "targets": [{ "accountId": "acc_ig1", "platform": "instagram" }]
  }'

Response

json

{
  "suggestionId": "sug_001",
  "scheduledFor": "2026-04-09T09:30:00.000Z",
  "targets": [{ "accountId": "acc_ig1", "platform": "instagram" }]
}

API Reference

Endpoints

Credits

GET/api/v1/credits/balance

credits:readGet credit balance

Get credit balance

Response Example

GET /api/v1/credits/balance

json

{ "balance": 5000 }

GET/api/v1/credits/cost-preview

credits:readPreview generation cost

Preview generation cost

Query Parameters

Param	Type	Description
`type`*	string	"text", "image", or "video"

Response Example

GET /api/v1/credits/cost-preview

json

{ "type": "image", "cost": 50, "currentBalance": 5000 }

Content Generation

POST/api/v1/content

5-20 crcontent:writeGenerate content (text)

Generate content (text)

Request Body

Field	Type	Description
`prompt`*	string	Content topic or description
`businessId`*	string	Business ID from /businesses
`contentFormat`	string	IMAGE, VIDEO, CAROUSEL, REEL, STORY, TEXT. Default: IMAGE
`useContentDNA`	boolean	Match proven tone from past viral posts. Default: false
`language`	string	Override output language (e.g. "he", "es"). Omit to auto-detect from DNA
`suggestionCount`	number	1-6 suggestions. Default: 4

Response Example

POST /api/v1/content

json

{
  "sessionId": "ses_...",
  "suggestions": [{
    "id": "sug_...",
    "title": "...",
    "body": "...",
    "contentFormat": "IMAGE",
    "tags": ["yoga", "wellness"]
  }],
  "creditsUsed": 20,
  "balanceAfter": 4980
}

GET/api/v1/content/[id]

content:readGet generated content

Get generated content

Response Example

GET /api/v1/content/[id]

json

{
  "id": "sug_...",
  "title": "...",
  "body": "...",
  "contentFormat": "IMAGE",
  "tags": ["yoga"],
  "images": [{ "imageUrl": "https://...", "orderIndex": 0 }]
}

POST/api/v1/content/[id]/image

50 crcontent:writeGenerate AI image

Generate AI image

Request Body

Field	Type	Description
`imageIndex`	number	Slide index for carousels (0-based). Default: 0
`customPrompt`	string	Override the auto-generated image prompt

Response Example

POST /api/v1/content/[id]/image

json

{ "imageUrl": "https://...", "creditsUsed": 50 }

Uses the suggestion's stored imagePrompts by default. For carousels, call once per slide.

Posting & Scheduling

POST/api/v1/content/[id]/post

post:writePost to platforms

Post to platforms

Request Body

Field	Type	Description
`targets`*	array	[{ accountId, platform }] — one or more targets
`scheduledFor`	string	ISO 8601 datetime for delayed publishing. Prefer /schedule for this.

Response Example

POST /api/v1/content/[id]/post

json

{
  "suggestionId": "sug_...",
  "results": [{
    "platform": "instagram",
    "status": "success",
    "postUrl": "https://instagram.com/p/..."
  }]
}

POST/api/v1/content/[id]/schedule

post:writeSchedule for future publishing

Schedule for future publishing

Request Body

Field	Type	Description
`scheduledFor`*	string	ISO 8601 datetime in the future
`targets`*	array	[{ accountId, platform }]

Response Example

POST /api/v1/content/[id]/schedule

json

{
  "suggestionId": "sug_...",
  "scheduledFor": "2026-04-09T09:30:00.000Z",
  "targets": [{ "accountId": "acc_ig1", "platform": "instagram" }]
}

Posts are published automatically within ~2 minutes of the scheduled time.

GET/api/v1/schedule/optimal-time

post:writeGet AI-recommended posting time

Get AI-recommended posting time

Query Parameters

Param	Type	Description
`businessId`*	string	Business to analyze
`accountIds`	string	Comma-separated account IDs to narrow analysis

Response Example

GET /api/v1/schedule/optimal-time

json

{
  "success": true,
  "data": {
    "scheduledDateTime": "2026-04-09T09:30:00.000Z",
    "confidence": 0.87,
    "reasoning": "Highest engagement on Wednesday mornings"
  }
}

DELETE/api/v1/content/[id]/post

post:writeCancel a scheduled post

Cancel a scheduled post

Response Example

DELETE /api/v1/content/[id]/post

json

{ "suggestionId": "sug_...", "cancelled": true }

Only works for posts with SCHEDULED status.

GET/api/v1/content/[id]/status

content:readCheck post status

Check post status

Response Example

GET /api/v1/content/[id]/status

json

{
  "id": "sug_...",
  "status": "POSTED",
  "platforms": [{
    "platform": "instagram",
    "postUrl": "https://instagram.com/p/..."
  }]
}

Video

POST/api/v1/video

500 crcontent:writeGenerate AI video (async)

Generate AI video (async)

Request Body

Field	Type	Description
`prompt`*	string	Scene description with subject, action, camera, mood
`duration`	number	4, 6, or 8 seconds. Default: 8
`aspectRatio`	string	"9:16" (vertical) or "16:9" (horizontal). Default: 9:16
`style`	string	"realistic", "animated", "cinematic", "social". Default: social

Response Example

POST /api/v1/video

json

{ "operationId": "op_...", "status": "processing" }

Async — poll /video/[operationId] every 10-15s until status is "completed".

GET/api/v1/video/[operationId]

content:readCheck video generation status

Check video generation status

Response Example

GET /api/v1/video/[operationId]

json

{
  "operationId": "op_...",
  "status": "completed",
  "videoUrl": "https://...",
  "duration": 8
}

Media Upload

POST/api/v1/content/upload-media

0 crcontent:writeUpload user media from URL

Upload user media from URL

Request Body

Field	Type	Description
`mediaUrl`*	string	HTTPS URL to image/video. Max 8MB images, 100MB videos
`businessId`*	string	Business ID
`caption`*	string	Caption text for the post
`contentFormat`*	string	IMAGE, VIDEO, CAROUSEL, REEL, STORY
`title`	string	Optional title. Defaults to first 50 chars of caption
`tags`	string[]	Hashtags without # prefix
`mediaUrls`	string[]	For CAROUSEL only: 2-10 image URLs (replaces mediaUrl)

Response Example

POST /api/v1/content/upload-media

json

{
  "suggestionId": "sug_...",
  "sessionId": "ses_...",
  "contentFormat": "IMAGE",
  "mediaUrl": "https://...",
  "creditsUsed": 0
}

Images are auto-processed to 1080x1080. Videos are stored as-is. TikTok only accepts VIDEO format.

Accounts & Businesses

GET/api/v1/accounts

accounts:readList social accounts

List social accounts

Query Parameters

Param	Type	Description
`businessId`	string	Filter accounts by business

Response Example

GET /api/v1/accounts

json

{
  "accounts": [{
    "id": "acc_...",
    "platform": "instagram",
    "username": "@themorningcup",
    "followers": 12500
  }]
}

GET/api/v1/businesses

businesses:readList businesses

List businesses

Response Example

GET /api/v1/businesses

json

{
  "businesses": [{
    "id": "biz_...",
    "name": "The Morning Cup",
    "type": "cafe",
    "industry": "food"
  }]
}

Base URL: https://www.fluxsocial.app · All endpoints return JSON. Rate limit headers included on every response.

Errors

Error Responses

All errors follow a consistent JSON format. The status field in the body always matches the HTTP status code.

Error format

json

{
  "error": {
    "message": "Human-readable error description",
    "status": 400
  }
}

Status Codes

Code	Meaning	When it happens
`400`	Bad Request	Missing or invalid parameters
`401`	Unauthorized	Missing or invalid API key
`402`	Insufficient Credits	Not enough credits for the operation. Body includes currentBalance.
`403`	Forbidden	API key lacks the required scope
`404`	Not Found	Resource (suggestion, business, account) does not exist or is not owned by you
`408`	Request Timeout	Media download timed out (upload-media)
`413`	Payload Too Large	Uploaded media exceeds size limit (8MB images, 100MB videos)
`415`	Unsupported Media	Uploaded file is not a supported image/video type
`429`	Rate Limited	Too many requests. Body includes retryAfter (seconds).
`500`	Server Error	Unexpected internal error — retry or contact support
`503`	Service Unavailable	External service (AI model, platform API) is temporarily down

402 and 429 extras: A 402 includes currentBalance in the body. A 429 includes retryAfter (seconds until reset).

Rate Limits

Rate Limiting

Every response includes rate limit headers so you can track your usage.

Rate limit headers

http

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1735689600

Content generation

API: 10 / hr

Web: 20 / hr

Image generation

API: 5 / hr

Web: 10 / hr

General endpoints

API: 60 / hr

Web: 100 / hr

MCP Server

Use FluxSocial from AI Tools

FluxSocial exposes a remote Model Context Protocol server. Connect Claude Desktop, Cursor, or any MCP-compatible client to generate and publish social media content with natural language. No local install or CLI tools required.

How It Works

1Connect

Add the FluxSocial MCP URL in your AI tool. Authentication uses OAuth — you will be prompted to sign in with your API key.

2Prompt

Ask your AI assistant to create content in natural language. It calls FluxSocial tools behind the scenes.

3Publish

Review the generated content and tell the assistant to post it. It handles multi-platform publishing automatically.

Setup Guide

First, create an API key in Settings → API Keys. Then follow the instructions for your AI tool below.

Open MCP settings

In Claude Desktop, go to Settings → Developer → Edit Config. This opens claude_desktop_config.json.

Add FluxSocial to your config

claude_desktop_config.json

json

{
  "mcpServers": {
    "fluxsocial": {
      "type": "url",
      "url": "https://www.fluxsocial.app/api/mcp"
    }
  }
}

Restart & authorize

Restart Claude Desktop. On first use, your browser will open a secure authorization page — paste your API key to connect.

Requires Claude Desktop v0.9 or later with remote MCP support. The "type": "url" field is required for remote servers — do not omit it.

Secure by design

Authentication follows the MCP OAuth 2.1 specification with PKCE. Your API key is encrypted during the authorization flow and never exposed in URLs or config files. The server supports dynamic client registration (RFC 7591) and metadata discovery (RFC 8414).

Available Tools

get_credit_balanceCheck remaining credits

preview_costPreview cost before generation

generate_contentGenerate captions, titles & hashtags

get_contentRetrieve content by ID

generate_imageCreate AI image for a suggestion (50 credits)

generate_videoCreate AI video via Veo 3 (500 credits, async)

check_video_statusPoll async video generation progress

post_contentPublish to social platforms

schedule_contentSchedule content for future publishing

get_optimal_timeGet AI-recommended best posting time

cancel_scheduled_postCancel a pending scheduled post

check_post_statusCheck posting status

upload_mediaUpload user media from URL (0 credits)

list_accountsList connected accounts

list_businessesList your businesses

All tools use the same credit pool as the REST API and web app. Rate limits apply per API key.

Example Conversation

Claude Desktop — FluxSocial connected

YouGenerate an Instagram post about morning coffee routines for my cafe.

ClaudeI'll generate that for you. Let me find your business first.

Tool calllist_businesses → 1 business found: "The Morning Cup"

Tool callgenerate_content → prompt: "Morning coffee routines", format: IMAGE

ClaudeDone — here's your post: "Rise & grind — your morning ritual starts here..." with 3 hashtag suggestions. Want me to post it to Instagram?

YouYes, post it.

Tool callpost_content → posted to Instagram (@themorningcup)

ClaudePosted! You can see it live at instagram.com/p/... — 20 credits used, 4,980 remaining.

API Keys

Scopes & Permissions

Keys are created with a set of scopes that limit what they can do. Scope your keys to the minimum permissions your integration needs.

credits:readRead credit balance and cost previews

content:readRead generated content and post status

content:writeGenerate new content (costs credits)

post:writePublish and schedule content to connected platforms

accounts:readList connected social accounts

businesses:readList businesses

Ready to build?

Create an account, generate an API key, and start in minutes.

Create Free Account View Pricing