API Stability
Flow uses a stability classification system to help you build with confidence. This page defines what each classification means and lists the current stable API surface.
Stability Classifications
Stable
Stable endpoints are production-ready and covered by our backward compatibility guarantee:
- No breaking changes without a major version bump and deprecation period
- Fully documented with examples, error codes, and SDK support
- Tested extensively in production workloads
Beta
Beta endpoints are functional but may change:
- Available for early adopters and experimentation
- Not covered by backward compatibility guarantees
- May be promoted to stable or removed based on feedback
- Not documented in public docs until promoted
Private
Private endpoints are internal-only:
- Used by Flow's own applications
- Not available for external use
- May change or be removed at any time without notice
Stable API Surface (v1)
The following endpoints are stable and safe to build upon. All endpoints use the base URL https://api.flowsocial.app/v1.
API Keys
Manage API keys for authentication.
| Method | Endpoint | Description |
|---|---|---|
GET | /api-keys | List all API keys |
POST | /api-keys | Create a new API key |
GET | /api-keys/{id} | Get a specific API key |
PATCH | /api-keys/{id} | Update an API key |
DELETE | /api-keys/{id} | Revoke an API key |
Channels
Manage content channels for organizing posts.
| Method | Endpoint | Description |
|---|---|---|
GET | /channels | List all channels |
POST | /channels | Create a new channel |
GET | /channels/{id} | Get a specific channel |
PATCH | /channels/{id} | Update a channel |
DELETE | /channels/{id} | Delete a channel |
Posts
Create, schedule, and manage social media posts.
| Method | Endpoint | Description |
|---|---|---|
GET | /posts | List posts (supports filtering, sorting, pagination) |
POST | /posts | Create a new post (supports Idempotency-Key) |
GET | /posts/{id} | Get a specific post |
PATCH | /posts/{id} | Update a post |
DELETE | /posts/{id} | Delete a post |
POST | /posts/preflight | Validate a post before creating |
POST | /posts/batch | Create multiple posts |
PATCH | /posts/batch | Update multiple posts |
DELETE | /posts/batch | Delete multiple posts |
Connections
Manage social media account connections.
| Method | Endpoint | Description |
|---|---|---|
GET | /connections | List all connections |
DELETE | /connections/{id} | Remove a connection |
POST | /connections/{id}/add-to-channel | Add connection to a channel |
POST | /connections/{id}/refresh | Refresh connection tokens |
POST | /connections/{id}/verify | Verify connection status |
POST | /connections/verify-channel/{channelId} | Verify all connections in a channel |
OAuth Flows (Browser-based)
These endpoints initiate OAuth flows and must be opened in a browser:
| Method | Endpoint | Description |
|---|---|---|
GET | /connections/twitter/auth | Start Twitter OAuth |
GET | /connections/twitter/callback | Twitter OAuth callback |
GET | /connections/linkedin/auth | Start LinkedIn OAuth |
GET | /connections/linkedin/callback | LinkedIn OAuth callback |
GET | /connections/meta/auth | Start Meta (Facebook/Instagram) OAuth |
GET | /connections/meta/callback | Meta OAuth callback |
GET | /connections/tiktok/auth | Start TikTok OAuth |
GET | /connections/tiktok/callback | TikTok OAuth callback |
Media
Upload and manage media attachments for posts.
| Method | Endpoint | Description |
|---|---|---|
POST | /media/upload | Upload a media file |
GET | /media/{key} | Get media metadata |
DELETE | /media/{key} | Delete a media file |
Webhooks
Configure webhooks for real-time event notifications.
| Method | Endpoint | Description |
|---|---|---|
GET | /webhooks | List all webhooks |
POST | /webhooks | Create a new webhook |
GET | /webhooks/{id} | Get a specific webhook |
PATCH | /webhooks/{id} | Update a webhook |
DELETE | /webhooks/{id} | Delete a webhook |
GET | /webhooks/{id}/deliveries | Get delivery history |
POST | /webhooks/{id}/test | Send a test event |
Usage
Monitor your API usage and limits.
| Method | Endpoint | Description |
|---|---|---|
GET | /usage | Get current usage summary |
GET | /usage/history | Get historical usage data |
GET | /usage/day | Get usage for a specific day |
Beta/Private Endpoints
The following endpoints exist but are not yet stable. Do not rely on them for production integrations:
- Channels (advanced): seeds, templates, analytics, capacity, context, optimize, AI-optimized posts, share/import, collaborators
- Analytics:
/analytics/usage,/analytics/endpoints,/analytics/errors - Metrics:
/metrics
These endpoints may be promoted to stable in future releases. Check the Changelog for updates.
Backward Compatibility Promise
For stable endpoints, we guarantee:
- No removal of endpoints without a 6-month deprecation notice
- No removal of response fields without a deprecation period
- No change to the meaning of existing fields
- Additive changes only: new optional fields, new endpoints, new optional parameters
We may add new fields to responses at any time. Your code should ignore unknown fields.
Promotion Process
Endpoints move from beta to stable when they meet these criteria:
- Contract finalized: Request/response schemas are locked
- Error handling complete: All error codes documented
- SDK support: Available in TypeScript SDK (Python/Go follow)
- Troubleshooting entry: Common issues documented
- Examples added: curl + SDK examples for all operations
- Production tested: Used successfully in real workloads
See Releasing Endpoints for the full checklist.