Migration Guide: Internal API to Public API

This guide helps you migrate from using Flow's internal API endpoints to the public /v1/* API endpoints.

Overview

Flow's API has evolved from internal-only endpoints to a fully public API. This migration guide covers:

• Endpoint changes
• Authentication changes
• Response format changes
• Breaking changes and deprecations

Authentication Migration

Before (Internal API)

Internal API used session-based authentication (cookies):

// Session-based (cookies)
fetch('/api/posts', {
  credentials: 'include', // Sends cookies
});

After (Public API)

Public API uses API key authentication (Bearer tokens):

// API key-based (Bearer token)
fetch('https://api.flowsocial.app/v1/posts', {
  headers: {
    'Authorization': 'Bearer flow_sk_live_abc12345_xyz789...',
  },
});

Migration Steps

1. Create an API key in Settings → Developer
2. Store the API key securely (environment variable, secret manager)
3. Update all API calls to use Bearer token authentication
4. Remove cookie-based authentication code

Endpoint Migration

Base URL Changes

Before	After
/api/posts	/v1/posts
/api/channels	/v1/channels
/api/connections	/v1/connections
/api/webhooks	/v1/webhooks

Endpoint Mapping

Posts

Before	After	Notes
GET /api/posts	GET /v1/posts	Same functionality
POST /api/posts	POST /v1/posts	Same functionality
DELETE /api/posts/:id	DELETE /v1/posts/:id	Same functionality
-	PATCH /v1/posts/:id	New: Update posts
-	POST /v1/posts/batch	New: Bulk operations

Channels

Before	After	Notes
GET /api/channels	GET /v1/channels	Same functionality
POST /api/channels	POST /v1/channels	Same functionality
DELETE /api/channels/:id	DELETE /v1/channels/:id	Same functionality
-	PATCH /v1/channels/:id	New: Update channels
-	GET /v1/channels/:id	New: Get channel details

Connections

Before	After	Notes
GET /api/connections	GET /v1/connections	Same functionality
DELETE /api/connections/:id	DELETE /v1/connections/:id	Same functionality
GET /api/connections/twitter/auth	GET /v1/connections/twitter/auth	OAuth flows unchanged
GET /api/connections/meta/auth	GET /v1/connections/meta/auth	New: Meta OAuth
GET /api/connections/tiktok/auth	GET /v1/connections/tiktok/auth	New: TikTok OAuth

Webhooks

Before	After	Notes
GET /api/webhooks	GET /v1/webhooks	Same functionality
POST /api/webhooks	POST /v1/webhooks	Same functionality
DELETE /api/webhooks/:id	DELETE /v1/webhooks/:id	Same functionality
-	PATCH /v1/webhooks/:id	New: Update webhooks
-	GET /v1/webhooks/:id/deliveries	New: Delivery history

Response Format Changes

Before (Internal API)

Responses were often direct arrays or objects:

[
  {
    "id": "post_123",
    "content": "Hello",
    "status": "queued"
  }
]

After (Public API)

Responses follow a consistent format with metadata:

{
  "data": [
    {
      "id": "post_123",
      "content": "Hello",
      "status": "queued"
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": 1703123456000,
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}

Migration Steps

1. Update response parsing to access data property
2. Handle pagination via meta.pagination when listing resources
3. Update error handling to use new error format

Example:

// Before
const posts = await response.json(); // Direct array

// After
const { data, meta } = await response.json();
const posts = data;
const { pagination } = meta;

Error Format Changes

Before (Internal API)

Errors might have varied formats:

{
  "error": "Something went wrong"
}

After (Public API)

Errors follow a consistent format:

{
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    {
      "field": "channelId",
      "message": "Channel ID is required"
    }
  ]
}

Migration Steps

1. Update error handling to use new error format
2. Check message field for user-facing error messages
3. Check details field for validation errors

New Features

API Key Permissions

Public API supports fine-grained permissions:

// Create API key with specific permissions
const key = await flow.apiKeys.create({
  name: "Read-only key",
  permissions: ["posts:read", "channels:read"],
});

Migration: Review your API key permissions and create keys with least privilege.

Rate Limiting

Public API includes rate limiting with headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1703123456

Migration: Implement rate limit monitoring and handling (see Rate Limits Guide).

Webhook Signatures

Public API webhooks include signatures for verification:

Flow-Signature: t=1703123456,v1=abc123...

Migration: Implement webhook signature verification (see Webhooks Guide).

SDK Migration

TypeScript SDK

If you're using the TypeScript SDK, update to the latest version:

npm install @flowdev/sdk@latest

The SDK automatically handles:

• Authentication (API keys)
• Rate limit retries
• Error parsing
• Request/response formatting

Python SDK

If you're using the Python SDK:

pip install flow-sdk --upgrade

Breaking Changes

Removed Endpoints

The following internal endpoints are no longer available:

• /api/usage → Use /v1/usage instead
• /api/billing → Use /v1/billing instead (if applicable)

Changed Behavior

1. Authentication required - All /v1/* endpoints require API key authentication
2. Rate limiting - All endpoints are rate limited
3. Pagination - List endpoints now return paginated responses
4. Error format - Errors follow consistent format

Migration Checklist

• Create API key in Settings → Developer
• Store API key securely (environment variable)
• Update base URL from /api/* to /v1/*
• Replace session auth with Bearer token auth
• Update response parsing to handle data property
• Implement pagination handling for list endpoints
• Update error handling to use new error format
• Implement rate limit monitoring
• Update webhook handlers to verify signatures
• Test all API calls in staging environment
• Update SDK to latest version (if using SDK)
• Update documentation and code comments

Testing

Use the staging environment to test your migration:

const flow = new Flow('flow_sk_test_...', {
  baseURL: 'https://api-staging.flowsocial.app',
});

Rollback Plan

If you need to rollback:

1. Keep internal API endpoints available during migration period
2. Use feature flags to switch between internal and public API
3. Monitor error rates and rollback if issues occur

Support

• Migration Help: support@flowsocial.app
• Documentation: https://docs.flowsocial.app
• GitHub Issues: https://github.com/flowsocial/flow/issues

Timeline

• Phase 1 (Months 1-3): Internal API remains available, public API in beta
• Phase 2 (Months 4-6): Public API stable, internal API deprecated
• Phase 3 (Months 7+): Internal API removed, public API only

Current Status: Public API is stable and recommended for all new integrations.