API docs by Redocly

FlowState API (1.0.0)

Download OpenAPI specification:

URL: https://github.com/MHanutko/flowstate.bot License: ISC

FlowState is a premier sports team asset generation platform built for scale. This API enables Data to Content Automation, allowing you to programmatically generate professional, broadcast-quality graphics from your dynamic data sources.

Getting Started

To get started with the FlowState API, contact your account manager to receive your API credentials. API key management via the dashboard is coming soon.

Authentication

All public API endpoints require authentication via the x-api-key header in your HTTP request.

GET /api/v1/templates HTTP/1.1
Host: flowstate.bot
x-api-key: your_api_key_here

The Automation Mental Model

FlowState is designed for chaining automated workflows:

  1. Data Sources: Connect external data (e.g., sports feeds).
  2. Automations: Map incoming data to specific graphic templates.
  3. Templates & Jobs: The core engine that renders images/videos based on your data.
  4. Destinations: Automatically upload rendered assets to your configured cloud storage (Google Drive, S3, etc.).

Health

Service health and status endpoints

Health check and root endpoint

Returns service status or serves the React frontend application

Authorizations:
cookieAuthApiKeyAuth

Responses

Authentication

Google OAuth authentication endpoints

Initiate Google OAuth flow

Redirects user to Google OAuth consent screen. After consent, Google redirects to /auth/google/callback.

Authorizations:
cookieAuthApiKeyAuth

Responses

Google OAuth callback handler

Handles the OAuth callback from Google. On success, redirects to / with session cookie set. On failure, redirects to /auth/login-failed.

Authorizations:
cookieAuthApiKeyAuth
query Parameters
code
required
string

OAuth authorization code from Google

state
string

OAuth state parameter

Responses

Logout user

Destroys the user session and clears authentication cookies

Authorizations:
cookieAuthApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Failed login redirect page

Returns error information when OAuth authentication fails

Authorizations:
cookieAuthApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get current authenticated user

Returns the currently logged-in user's profile information

Authorizations:
cookieAuthApiKeyAuth

Responses

Response samples

Content type
application/json
{}

Get current user (API v1)

Returns the currently authenticated user's profile information

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
{}

Assets

Asset generation and rendering

Generate single asset

Renders a single PNG asset from uploaded logo and team color.

Process:

  1. Upload logo file (PNG/JPG/GIF/SVG)
  2. Provide hex color (e.g., #FF5733)
  3. Select template ID
  4. Receive rendered PNG asset
Authorizations:
cookieAuth
Request Body schema: multipart/form-data
required
logo
required
string <binary>

Team logo file (PNG, JPG, GIF, SVG)

teamHomeColor
required
string^#[0-9A-Fa-f]{6}$

Hex color code (with

template
required
string

Template ID from /api/v1/templates

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Templates

Template discovery, analysis, and metadata

List available templates

Returns metadata for all available templates including:

  • Template ID and display name
  • Description and dimensions
  • Output format and naming pattern
  • Required placeholders
Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false
}

Workflows

Multi-asset workflow execution

List available workflows

Returns all available workflows. A workflow defines a sequence of templates to generate from shared input data (e.g., generate logo, banner, and social media assets from one set of team data).

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": false
}

Get workflow details

Returns detailed workflow configuration including field schema for form generation. Use this to build dynamic forms for workflow execution.

Authorizations:
cookieAuth
path Parameters
id
required
string
Example: team-asset-package

Workflow ID

Responses

Response samples

Content type
application/json
{
  • "object": "workflow",
  • "data": {
    }
}

Execute workflow

Executes a workflow with provided data and generates all assets defined in the workflow. Returns a ZIP archive containing all generated assets organized by template.

Process:

  1. Upload required files (logos, images)
  2. Provide form data (text, colors)
  3. Workflow generates all configured templates
  4. Receive ZIP archive with all assets
Authorizations:
cookieAuth
path Parameters
id
required
string
Example: team-asset-package

Workflow ID

Request Body schema: multipart/form-data
required
property name*
additional property
any

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Debug workflow configuration

Diagnostic endpoint that returns information about the workflows directory, loaded workflows, and any configuration errors. No authentication required.

Authorizations:
cookieAuthApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "cwd": "string",
  • "workflowsDir": "string",
  • "exists": true,
  • "files": [
    ],
  • "loadedWorkflows": 0,
  • "workflows": [
    ]
}

Jobs

Render job management and automation

Create a new render job

Initiates a new background render job. Perfect for automation workflows where data is pushed to FlowState to generate a graphic.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
templateId
required
string
data
required
object

Key-value pairs matching template placeholders

Responses

Request samples

Content type
application/json
{
  • "templateId": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "jobId": "string"
}

Get recent jobs

Retrieves a list of recently executed jobs for the organization.

Authorizations:
cookieAuthApiKeyAuth

Responses

Get job status

Poll this endpoint to check if an automated render job has completed.

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Delete a single job

Removes a render job and its associated assets from the system.

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Publish a completed job

Manually trigger the publishing of a completed render job to configured destinations (e.g., Google Drive, AWS S3).

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Bulk delete jobs

Allows deletion of multiple render jobs in a single request.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
jobIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "jobIds": [
    ]
}

Automations

Webhooks and payload mapping rules

List automations

Returns a list of all configured automations for the organization, detailing how incoming data maps to templates.

Authorizations:
cookieAuthApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an automation

Creates a new automation rule mapping an incoming data source webhook payload to a specific graphic template's placeholders.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
name
required
string
data_source_id
required
string

The ID of the source generating the data.

target_type
required
string
Enum: "template" "workflow"
template_id
string

Required if target_type is 'template'.

mappings
object

JSONPath rules to map data source fields to template placeholders.

Responses

Request samples

Content type
application/json
{
  • "name": "Match Events to Social Graphics",
  • "data_source_id": "string",
  • "target_type": "template",
  • "template_id": "string",
  • "mappings": { }
}

Trigger automation webhook

Production webhook URL where external systems (like live data providers or custom apps) POST their JSON payloads. This triggers any active automations linked to this data source, automatically generating graphics in the background.

Authorizations:
cookieAuthApiKeyAuth
path Parameters
slug
required
string

Unique webhook slug generated by FlowState upon Data Source creation.

Request Body schema: application/json
required
object

The arbitrary JSON payload required by the connected Automations.

Responses

Request samples

Content type
application/json
{ }

Destinations

Publishing integrations (Google Drive, S3, etc.)

List publishing destinations

Returns a list of all external publishing destinations (e.g., Google Drive, AWS S3, Webhooks) where completed renders are sent.

Authorizations:
cookieAuthApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a destination

Connects a new external destination for automated publishing of generated assets.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
name
required
string
type
required
string
Enum: "gdrive" "s3" "webhook" "email"
config
required
object

Destination-specific authentication and configuration settings.

Responses

Request samples

Content type
application/json
{
  • "name": "Marketing Google Drive",
  • "type": "gdrive",
  • "config": { }
}

Data Sources

Incoming data configurations

List data sources

Returns a list of all data sources configured for the organization.

Authorizations:
cookieAuthApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a data source

Creates a new data source (e.g., a webhook receiver or a REST polling config) to ingest external data into FlowState.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
name
required
string
type
required
string
Enum: "WEBHOOK" "REST_GET"
config
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "WEBHOOK",
  • "config": { }
}

Entities

Sports data (Teams, Leagues, Clubs)

Get entity statistics

Returns counts of all sports entities (Teams, Players, Clubs, Leagues, Sports).

Authorizations:
cookieAuthApiKeyAuth

Responses

List sports

Authorizations:
cookieAuthApiKeyAuth

Responses

Create a sport

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
name
required
string
icon_url
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "icon_url": "string"
}

Get sport by ID

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Update sport

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Delete sport

Fails with 409 if leagues reference this sport.

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

List leagues

Authorizations:
cookieAuthApiKeyAuth
query Parameters
sport_id
string
country_id
string

Responses

Create a league

Authorizations:
cookieAuthApiKeyAuth

Responses

Get league by ID

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Update league

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Delete league

Fails with 409 if active teams reference this league.

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

List teams

Returns a paginated list of teams.

Authorizations:
cookieAuthApiKeyAuth
query Parameters
league_id
string
club_id
string
active
string
Enum: "true" "false" "all"

Responses

Create a team

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
name
required
string
abbreviation
string
logo_url
string
primary_color
string
secondary_color
string
club_id
string
league_id
string
external_id
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "abbreviation": "string",
  • "logo_url": "string",
  • "primary_color": "string",
  • "secondary_color": "string",
  • "club_id": "string",
  • "league_id": "string",
  • "external_id": "string"
}

Search teams

Authorizations:
cookieAuthApiKeyAuth
query Parameters
q
required
string >= 2 characters
limit
integer
Default: 20

Responses

Get team by ID

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Update team

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Delete team (soft delete)

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

List players

Returns a paginated list of players with team/league joins.

Authorizations:
cookieAuthApiKeyAuth
query Parameters
team_id
string
league_id
string
active
string
Enum: "true" "false" "all"

Responses

Create a player

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
first_name
required
string
last_name
required
string
jersey_number
integer [ 0 .. 999 ]
position
string
image_url
string
team_id
required
string <uuid>
external_player_id
string

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "jersey_number": 999,
  • "position": "string",
  • "image_url": "string",
  • "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
  • "external_player_id": "string"
}

Search players

Authorizations:
cookieAuthApiKeyAuth
query Parameters
q
required
string >= 2 characters
limit
integer
Default: 20

Responses

Get player by ID

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Update player

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Delete player (soft delete)

Authorizations:
cookieAuthApiKeyAuth
path Parameters
id
required
string

Responses

Import entities from CSV

Import teams or players from CSV. Use entity_type 'players' for player imports.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: application/json
required
csv_content
required
string
mapping
required
object
options
object
entity_type
string
Default: "teams"
Enum: "teams" "players"

Responses

Request samples

Content type
application/json
{
  • "csv_content": "string",
  • "mapping": { },
  • "options": { },
  • "entity_type": "teams"
}

Integrations

Third-party service configurations (e.g., Magnifi)

Batch

Batch processing operations

Generate batch assets

Processes CSV file with multiple teams and generates all templates for each team. Returns ZIP archive with organized folder structure.

CSV Format:

logoHomePath,teamHomeColor
TeamName1.png,#FF5733
TeamName2.png,#3498DB

Output Structure:

batch_assets.zip
├── TeamName1/
│   ├── Angled Logo.png
│   ├── Square Logo.png
│   └── Banner.png
└── TeamName2/
    ├── Angled Logo.png
    ├── Square Logo.png
    └── Banner.png
Authorizations:
cookieAuth
Request Body schema: multipart/form-data
required
csvFile
required
string <binary>

CSV file with team data (logoHomePath, teamHomeColor)

logoFiles
required
Array of strings <binary> [ items <binary > ]

Multiple logo files matching CSV logoHomePath column

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Generate batch assets (Legacy) Deprecated

DEPRECATED: Use /api/v1/batch-render instead.

This endpoint is kept for backward compatibility.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: multipart/form-data
required
csv
required
string <binary>

CSV file with team data

logos
required
Array of strings <binary> [ items <binary > ]

Multiple logo files

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Legacy

Deprecated endpoints (kept for backward compatibility)

List available templates (Legacy) Deprecated

DEPRECATED: Use /api/v1/templates instead.

This endpoint is kept for backward compatibility.

Authorizations:
cookieAuthApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "templates": [
    ]
}

Generate single asset (Legacy) Deprecated

DEPRECATED: Use /api/v1/render instead.

This endpoint is kept for backward compatibility.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: multipart/form-data
required
logo
required
string <binary>

Team logo file (PNG, JPG, GIF, SVG)

teamHomeColor
required
string^#[0-9A-Fa-f]{6}$

Hex color code (with

template
required
string

Template ID from /api/templates

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Generate batch assets (Legacy) Deprecated

DEPRECATED: Use /api/v1/batch-render instead.

This endpoint is kept for backward compatibility.

Authorizations:
cookieAuthApiKeyAuth
Request Body schema: multipart/form-data
required
csv
required
string <binary>

CSV file with team data

logos
required
Array of strings <binary> [ items <binary > ]

Multiple logo files

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}