API docs by Redocly

FlowState API (1.0.0)

Download OpenAPI specification:

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

Sports team asset generation tool - Automated rendering of team graphics using HTML templates and Puppeteer browser automation.

Features

  • Single asset generation with custom templates
  • Batch processing from CSV files
  • Workflow execution for multi-asset generation
  • Dynamic template discovery
  • Google OAuth authentication
  • Transparent PNG output

Authentication

The API uses Google OAuth 2.0 for authentication. Most endpoints require authentication. Use the /auth/google endpoint to initiate the OAuth flow.

Usage

Upload team logos and colors to generate professional sports graphics.

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": [
    ]
}

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": {
    }
}