Skip to main content

API Overview

The Flow API is a RESTful API that allows you to programmatically schedule and manage social media posts across multiple platforms.

How Flow Works

Flow API Architecture
👨‍💻

Developer

Use SDK or API to create posts

🌊

Flow API

Manages channels, schedules, and delivery

📱

Platforms

Posts delivered to all connected platforms

🔔

Webhooks

Real-time notifications of delivery status

Base URL​

https://api.flowsocial.app/v1

Authentication​

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer flow_sk_live_abc12345_xyz789...

See the Authentication Guide for details.

Request Format​

All requests should include:

  • Content-Type: application/json header (for POST/PATCH requests)
  • Authorization: Bearer <your-api-key> header
  • JSON body for POST/PATCH requests

Response Format​

All responses are JSON objects. Successful responses include the requested data:

{
  "data": {
    "id": "channel_123",
    "name": "My Channel",
    "color": "#3B82F6"
  }
}

Error responses follow a standardized format:

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request",
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  }
}

Rate Limits​

  • Default: 100 requests per minute per API key
  • Post Creation: 30 requests per minute
  • Webhook Creation: 10 requests per minute
  • API Key Creation: 5 requests per minute

Rate limit headers are included in every response:

  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

See Rate Limits for details.

Pagination​

List endpoints support pagination using query parameters:

  • page: Page number (default: 1)
  • per_page: Items per page (default: 20, max: 100)

Example:

GET /v1/posts?page=2&per_page=50

Filtering​

Many list endpoints support filtering using query parameters:

GET /v1/posts?filter[status]=queued&filter[channelId]=channel_123

Advanced filtering is available using the filter query parameter:

GET /v1/posts?filter[status][eq]=queued&filter[scheduledFor][gte]=1703000000000

See Querying for details.

Sorting​

List endpoints support sorting using the sort parameter:

GET /v1/posts?sort=-scheduledFor  # Descending
GET /v1/posts?sort=scheduledFor    # Ascending

Idempotency​

POST requests support idempotency keys to prevent duplicate operations:

POST /v1/posts
Idempotency-Key: unique-key-123

Idempotency keys are valid for 24 hours.

Webhooks​

Configure webhooks to receive real-time notifications about events:

  • post.created - A new post has been scheduled
  • post.delivered - A post has been successfully published
  • post.failed - A post failed to publish
  • post.blocked - A post was blocked

See Webhooks for details.

Error Handling​

The API uses standard HTTP status codes:

  • 200 OK - Success
  • 201 Created - Resource created
  • 400 Bad Request - Invalid request
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

See Error Handling for details.

Endpoints​

Channels​

Manage channels for organizing your posts:

  • GET /v1/channels - List channels
  • POST /v1/channels - Create channel
  • GET /v1/channels/:id - Get channel details
  • PATCH /v1/channels/:id - Update channel
  • DELETE /v1/channels/:id - Delete channel

Posts​

Manage social media posts:

  • GET /v1/posts - List posts
  • POST /v1/posts - Create post
  • GET /v1/posts/:id - Get post details
  • PATCH /v1/posts/:id - Update post
  • DELETE /v1/posts/:id - Delete post
  • POST /v1/posts/batch - Create multiple posts
  • PATCH /v1/posts/batch - Update multiple posts
  • DELETE /v1/posts/batch - Delete multiple posts

Connections​

Manage platform connections:

  • GET /v1/connections - List connections
  • DELETE /v1/connections/:id - Delete connection
  • POST /v1/connections/:id/add-to-channel - Add connection to channel
  • POST /v1/connections/:id/refresh - Refresh connection token
  • POST /v1/connections/:id/verify - Verify connection status
  • POST /v1/connections/verify-channel/:channelId - Verify all connections in a channel

OAuth Flows (Browser-based)​

  • GET /v1/connections/twitter/auth - Start Twitter OAuth
  • GET /v1/connections/twitter/callback - Twitter OAuth callback
  • GET /v1/connections/linkedin/auth - Start LinkedIn OAuth
  • GET /v1/connections/linkedin/callback - LinkedIn OAuth callback
  • GET /v1/connections/meta/auth - Start Meta (Facebook/Instagram) OAuth
  • GET /v1/connections/meta/callback - Meta OAuth callback
  • GET /v1/connections/tiktok/auth - Start TikTok OAuth
  • GET /v1/connections/tiktok/callback - TikTok OAuth callback

Media​

Upload and manage media files:

  • POST /v1/media/upload - Upload media file
  • GET /v1/media/:key - Get media file
  • DELETE /v1/media/:key - Delete media file

Webhooks​

Manage webhooks:

  • GET /v1/webhooks - List webhooks
  • POST /v1/webhooks - Create webhook
  • GET /v1/webhooks/:id - Get webhook details
  • PATCH /v1/webhooks/:id - Update webhook
  • DELETE /v1/webhooks/:id - Delete webhook
  • GET /v1/webhooks/:id/deliveries - Get delivery history
  • POST /v1/webhooks/:id/test - Test webhook

API Keys​

Manage API keys:

  • GET /v1/api-keys - List API keys
  • POST /v1/api-keys - Create API key
  • GET /v1/api-keys/:id - Get API key details
  • PATCH /v1/api-keys/:id - Update API key
  • DELETE /v1/api-keys/:id - Delete API key

Usage​

Get usage information:

  • GET /v1/usage - Get current usage summary
  • GET /v1/usage/history - Get historical usage data
  • GET /v1/usage/day - Get usage for a specific day

SDKs​

Official SDKs are available for:

Support​