Flow Economy API

The Flow economy uses a dual-flow system to manage how many posts users can schedule per day.

Overview

Flow uses two types of flows:

• Daily Flows: Renewable credits that reset daily based on your subscription plan
• Bonus Flows: Non-renewable credits that can be earned, gifted, or acquired

Flow Consumption Order

When creating a post:

1. Daily flows are consumed first (free with your plan)
2. Bonus flows are used only when daily flows are exhausted
3. If both are empty, post creation is blocked

This ensures subscribers always get their daily allocation before using bonus credits.

Authentication

All endpoints require authentication via session cookie (web app) or Bearer token (API).

# API key authentication
Authorization: Bearer flow_sk_live_abc123...

Endpoints

Get Flow Balance

Retrieve your current flow availability.

GET /api/flows/balance

Response

{
  "daily": {
    "used": 3,
    "limit": 10,
    "remaining": 7
  },
  "bonus": {
    "available": 25
  },
  "total": {
    "available": 32
  }
}

Field	Description
daily.used	Number of daily flows consumed today
daily.limit	Maximum daily flows (from subscription plan)
daily.remaining	Daily flows remaining for today
bonus.available	Total bonus flows in your account
total.available	Combined available flows (daily remaining + bonus)

Get Transaction History

Retrieve your bonus flow transaction history.

GET /api/flows/transactions
GET /api/flows/transactions?limit=20

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Max transactions to return (1-100)

Response

{
  "transactions": [
    {
      "id": "tx_abc123",
      "type": "gift_received",
      "amount": 10,
      "balanceAfter": 35,
      "source": "user_gift",
      "note": "Happy birthday!",
      "createdAt": 1706000000000
    },
    {
      "id": "tx_def456",
      "type": "consumed",
      "amount": -1,
      "balanceAfter": 34,
      "source": "post_creation",
      "note": "Bonus flow consumed for post post_xyz",
      "createdAt": 1706000500000
    }
  ],
  "count": 2
}

Transaction Types

Type	Description
gift_sent	You sent flows to another user (negative amount)
gift_received	You received flows from another user
earned	Bonus flows earned (referral, promo, etc.)
consumed	Bonus flow used for post creation

Sources

Source	Description
user_gift	Flow gifted by another user
referral	Earned from referral program
promo	Promotional bonus
admin	Granted by administrator
signup_bonus	New user signup bonus
post_creation	Consumed when creating a post

Gift Flows to Another User

Send bonus flows to another Flow user.

POST /api/flows/gift
Content-Type: application/json

{
  "recipientEmail": "friend@example.com",
  "amount": 10,
  "note": "Great work on your content!"
}

Request Body

Field	Type	Required	Description
recipientEmail	string	Yes	Email of the recipient (must be a Flow user)
amount	integer	Yes	Number of flows to gift (1-100)
note	string	No	Optional message to include

Response

{
  "success": true,
  "transferred": 10,
  "yourBalance": 15,
  "recipientEmail": "friend@example.com",
  "transactionId": "tx_ghi789"
}

Error Responses

Status	Error	Description
400	Insufficient bonus flows	You don't have enough bonus flows
400	Cannot gift flows to yourself	Self-gifting not allowed
400	Maximum gift amount is 100 flows	Single transaction limit
400	Recipient not found	No user with that email

Grant Flows (Admin Only)

Grant bonus flows to a user. Requires admin privileges.

POST /api/flows/admin/grant
Content-Type: application/json

{
  "userEmail": "user@example.com",
  "amount": 50,
  "source": "promo",
  "note": "Beta tester reward"
}

Request Body

Field	Type	Required	Description
userEmail	string	Yes	Email of the user to receive flows
amount	integer	Yes	Number of flows to grant
source	string	No	Source identifier (default: "admin")
note	string	No	Admin note for the grant

Response

{
  "success": true,
  "granted": 50,
  "newBalance": 75,
  "userEmail": "user@example.com"
}

Usage in Post Creation

When creating a post via the API, flows are automatically consumed:

POST /api/posts
Content-Type: application/json

{
  "channelId": "channel_123",
  "content": "Hello world!",
  "scheduledFor": "2024-12-25T10:00:00Z"
}

The response includes flow consumption details:

{
  "id": "post_abc123",
  "content": "Hello world!",
  "scheduledFor": 1735128000000,
  "status": "queued",
  "flowSource": "daily"
}

The flowSource field indicates whether the post consumed a daily or bonus flow.

SDK Examples

TypeScript SDK

import { Flow } from '@flowdev/sdk';

const flow = new Flow('flow_sk_live_...');

// Check balance
const balance = await flow.flows.getBalance();
console.log(`Daily: ${balance.daily.remaining}/${balance.daily.limit}`);
console.log(`Bonus: ${balance.bonus.available}`);

// Gift flows
await flow.flows.gift({
  recipientEmail: 'friend@example.com',
  amount: 5,
  note: 'Keep creating great content!',
});

// Get transaction history
const { transactions } = await flow.flows.getTransactions({ limit: 10 });

Python SDK

from flow_sdk import Flow

flow = Flow('flow_sk_live_...')

# Check balance
balance = flow.flows.get_balance()
print(f"Daily: {balance['daily']['remaining']}/{balance['daily']['limit']}")
print(f"Bonus: {balance['bonus']['available']}")

# Gift flows
flow.flows.gift(
    recipient_email='friend@example.com',
    amount=5,
    note='Keep creating great content!'
)

Best Practices

Managing Flow Usage

1. Check balance before creating posts to provide better UX
2. Handle flow exhaustion gracefully with clear messaging
3. Consider bonus flows for burst posting when daily limit is reached

Gifting Flows

1. Validate recipient exists before attempting transfer
2. Use meaningful notes for tracking purposes
3. Implement rate limiting on your end for gift requests

Rate Limits

Flow economy endpoints share the standard API rate limits:

• 100 requests per minute per API key
• Gifting is limited to 100 flows per transaction

Webhooks

Flow transactions can trigger webhooks:

{
  "event": "flow.gift_received",
  "data": {
    "transactionId": "tx_abc123",
    "amount": 10,
    "senderId": "user_sender",
    "recipientId": "user_recipient",
    "note": "Gift message"
  },
  "timestamp": 1706000000000
}

See Webhooks Documentation for setup instructions.