API docs by Redocly

FlowState API (1.0.0)

Download OpenAPI specification:

URL: https://app.flowstate.bot/help/using-the-api License: ISC

FlowState is an enterprise sports-team asset generation platform. This API lets you operate FlowState programmatically with your organization's API key: create and manage templates, render single or batch assets, manage your sports-data entities, configure data sources and automations, and publish rendered assets to your destinations.

Authentication

Every endpoint is authenticated with a per-organization API key sent in the x-api-key header. Keys are generated by an org admin in the dashboard under Config -> API.

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

A request without a valid key returns 401. The key resolves your organization, and every resource you read or write is scoped to that organization automatically.

Scopes

API keys carry a list of scopes. Each operation below documents the scope it requires in its description. The available scopes are:

Scope Grants
read:jobs Read render jobs and their status
write:jobs Create, rerun, publish and delete render jobs (incl. renders and batches)
read:templates Read templates, versions, variants and sets
write:templates Create, update, publish and delete templates, versions, variants and sets
read:destinations Read publishing destinations
admin:org Super-scope: grants every other scope, and is required for destination and data-source mutations

Operations marked (any key) require only a valid key with no specific scope (entities, data sources, automations, flows, workflows, integrations, uploads, reports and tools have no granular scope yet). A 403 with { "error": "Insufficient API key scope", "required": [...], "missing": [...] } is returned when a key lacks the scope an operation needs.

Conventions

  • Base URL: https://flowstate.bot
  • Casing: Most resource responses are snake_case (for example template_id, created_at). A subset of endpoints (destinations, the batch/* storage helpers, upload-asset, tools/* and the reports/dashboard wrapper) return raw payloads in camelCase; the affected fields are documented as-is in each schema.
  • Item envelope: single resources are wrapped as { "object": "<type>", "data": { ... } }.
  • List envelope: collections are wrapped as { "object": "list", "data": [ ... ], "has_more": <bool>, "next_cursor": <string|null> }, sometimes with extra fields such as total or stats.
  • Legacy { success: true } envelope: destinations, the batch/* storage helpers, upload-asset and tools/* use a flatter { "success": true, ... } shape instead of the item/list envelope.
  • Errors: the standard error envelope is { "error": { "type", "code", "message", "param" } }. In production, 5xx messages are generic; scope and legacy { success: false } errors use a flatter shape (see the Scopes section).
  • Idempotency: mutating /api/v1 requests accept an optional Idempotency-Key header; a replay with the same key returns the original response.
  • Rate limits: limits are enforced per organization in three tiers - read (GET), write (POST/PUT/PATCH/DELETE) and render (/renders, workflow execution). Exceeding a tier returns 429.

Renders

Render single or multiple assets from a template.

Create an async render

Queue one asset render, or an array of renders in a single call. Requires the write:jobs scope. Accepts a single object or an array of objects; an array response is returned as a non-paginated list.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
One of
team_color
required
string

Team colour (hex).

template_id
string
Default: "angled-logo"
team_name
string
logo_url
string
webhook_url
string
type
string
Default: "template"
destination_ids
Array of strings <uuid> [ items <uuid > ]
object

Responses

Request samples

Content type
application/json
[ ]

Response samples

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

Render an asset synchronously

Render a single asset and return the resulting PNG directly in the response body. Requires the write:jobs scope. Image inputs are supplied either as uploaded files (one part per template field) or as URL fields named <fieldId>_url.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
template
string

Template id or slug. Defaults to angled-logo.

team_name
string
variant_id
string
color
string

Legacy templates - team colour (hex).

logo
string <binary>

Legacy templates - logo image file.

Responses

Response samples

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

Jobs

Render job lifecycle - create, inspect, publish, rerun and delete.

Create a render job

Create a render job from a template. Requires the write:jobs scope.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
template_id
required
string <uuid>
object

Field values for the template.

variant_id
string or null <uuid>

Responses

Request samples

Content type
application/json
{
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "data": { },
  • "variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6"
}

Response samples

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

Delete multiple jobs

Permanently delete a set of jobs by id. Requires the write:jobs scope.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
jobIds
required
Array of strings <uuid> non-empty [ items <uuid > ]

Responses

Request samples

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

Response samples

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

List recent jobs

Paginated list of the organization's recent jobs. Requires the read:jobs scope. The list envelope additionally includes total and a stats object.

Authorizations:
ApiKeyAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 25
offset
integer >= 0
Default: 0
search
string
type
string
Enum: "templates" "workflows"
source
string
Enum: "manual" "magnifi"
publish
string
Enum: "published" "unpublished"
team
string

Exact team name.

template
string

Token tpl:<id> or wf:<id>.

created_after
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string",
  • "total": 0,
  • "stats": {
    }
}

Get job filter options

Distinct team and template values for building job filters. Requires read:jobs.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Get a job

Fetch a single job by id. Requires the read:jobs scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Delete a job

Delete a single job. Requires the write:jobs scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Get job progress

Lightweight progress for fast polling. Requires the read:jobs scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Publish a completed job

Publish a completed job's asset to one or more destinations. The job must be completed with an output_url. Requires the write:jobs scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
destinationIds
required
Array of strings <uuid> non-empty [ items <uuid > ]

Responses

Request samples

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

Response samples

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

Rerun a job

Clone a completed or failed job into a new pending render. Requires write:jobs.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Batch

Template-centric batch renders and the storage-upload helpers.

Create a batch render

Create a template-centric batch render. Each row carries pre-resolved <field>_url values (upload logos first via /api/v1/batch/get-upload-link). Requires write:jobs. This endpoint returns a raw { data } payload (no object wrapper).

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
template_id
required
string <uuid>
required
Array of objects non-empty

One object per asset; carries <field>_url values. Legacy alias variants is accepted.

variant_ids
Array of strings <uuid> [ items <uuid > ]

Variants to fan out per row. Empty - the template default variant.

name_column
string
Default: ""

Responses

Request samples

Content type
application/json
{
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "rows": [
    ],
  • "variant_ids": [
    ],
  • "name_column": ""
}

Response samples

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

Retry failed rows of a batch

Re-queue the failed rows of a batch job. Requires the write:jobs scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Upload batch files

Upload a CSV plus one or more logo files for a batch. Returns a camelCase { success: true, ... } payload. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
csvFile
required
string <binary>
logoFiles
required
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "sessionId": "string",
  • "csvUrl": "string",
  • "logoStorageUrls": {
    },
  • "uploadedLogos": [
    ]
}

Submit a storage-backed batch for analysis

Submit storage URLs for analysis; returns the detected CSV structure and a session id. Returns a camelCase { success: true, ... } payload. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
sessionId
required
string
csvUrl
required
string
required
object

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "csvUrl": "string",
  • "logoStorageUrls": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "sessionId": "string",
  • "csvAnalysis": { },
  • "uploadedLogos": [
    ],
  • "message": "string"
}

Execute a storage-backed batch

Start processing a previously submitted batch session with a column mapping. Returns a camelCase { success: true, ... } payload with poll and download URLs. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
sessionId
required
string
required
object
skipFirstRow
boolean
Default: false
object

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "columnMapping": { },
  • "skipFirstRow": false,
  • "manualLogoAssignments": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "sessionId": "string",
  • "runId": "string",
  • "status": "processing",
  • "statusUrl": "string",
  • "downloadUrl": "string"
}

Get storage-backed batch status

Poll a batch session's status. Returns a camelCase { success: true, status, ... } payload.

Authorizations:
ApiKeyAuth
path Parameters
sessionId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "status": "processing",
  • "sessionId": "string"
}

Templates

Templates, their version history, preview and upload.

List templates

List the organization's templates. Requires the read:templates scope. The list view exposes the logo URL as thumbnail_url and omits html_content.

Authorizations:
ApiKeyAuth
query Parameters
include_live_status
string
Value: "true"

When true, each template includes a live_automation object (or null).

Responses

Response samples

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

Get a template

Fetch a single template. Requires the read:templates scope. The single view exposes the logo URL under the key thumbnail and includes html_content.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
query Parameters
include_live_status
string
Value: "true"

Responses

Response samples

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

Update a template

Update template metadata. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string
thumbnail_url
string
object
set_id
string or null <uuid>
club_hub_visible
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "thumbnail_url": "string",
  • "config": { },
  • "set_id": "516c4b88-fac0-4d1c-bb7a-9a8534cc5e71",
  • "club_hub_visible": true
}

Response samples

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

Delete a template

Soft-delete a template. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

List template versions

Master and per-variant version history. Requires the read:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Preview a template

Render a template to HTML for preview. Requires the read:templates scope. This endpoint returns a bare object (no item envelope). Only HTML engines are supported; async engines (AE, motion) return 400.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
team_id
string <uuid>
player_id
string <uuid>
object

Field value overrides.

version_id
string <uuid>
variant_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
  • "player_id": "f8b23bf6-c56d-4f96-b79c-96d80504663d",
  • "fields": { },
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  • "variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6"
}

Response samples

Content type
application/json
{
  • "html": "string",
  • "viewport": {
    },
  • "selector": "string"
}

Publish a template version

Make a specific version the published version. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
version_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c"
}

Response samples

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

Roll back to a version

Activate an earlier version. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
version_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c"
}

Response samples

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

Roll back a variant to a version

Activate an earlier scoped version of a variant. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
variantId
required
string <uuid>
Request Body schema: application/json
required
version_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c"
}

Response samples

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

Delete a template version

Delete a specific version. The published version and the last remaining version cannot be deleted. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
versionId
required
string <uuid>

Responses

Response samples

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

Clone a template

Create a copy of a template. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update a template thumbnail

Upload a new thumbnail image. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: multipart/form-data
required
thumbnail
required
string <binary>

Responses

Response samples

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

Upload a template package

Upload a template package (ZIP) as a multipart file field template_package. Requires the write:templates scope. Returns a { success, data, message } envelope.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
template_package
required
string <binary>
templateId
string <uuid>

Update an existing template instead of creating one.

set_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": { },
  • "message": "string"
}

Get a signed template upload URL

Get a signed URL to upload a large template package directly to storage. Requires the write:templates scope. The data fields are camelCase.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
filename
string
Default: "template.zip"

Responses

Request samples

Content type
application/json
{
  • "filename": "template.zip"
}

Response samples

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

Process an uploaded template package

Process a template package previously uploaded to storage. Depending on the flags this creates a new template, updates the master, creates a new variant, or adds a variant version. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
storagePath
required
string
templateId
string <uuid>
set_id
string <uuid>
asNewVariant
boolean
variant_name
string
targetVariantId
string <uuid>
change_summary
string

Responses

Request samples

Content type
application/json
{
  • "storagePath": "string",
  • "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
  • "set_id": "516c4b88-fac0-4d1c-bb7a-9a8534cc5e71",
  • "asNewVariant": true,
  • "variant_name": "string",
  • "targetVariantId": "a6f78b54-19c7-47eb-b6a7-1c0f19171a23",
  • "change_summary": "string"
}

Response samples

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

Create a motion template from FSCJ

Create a Motion (FSCJ to GSAP) template directly from an FSCJ document. Requires write:templates.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
object
name
string
change_summary
string

Responses

Request samples

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

Response samples

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

Sets

Named groupings of templates.

List sets

List the organization's sets. Requires the read:templates scope.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "object": "item",
  • "data": [
    ]
}

Create a set

Create a new set. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string
color
string
description
string

Responses

Request samples

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

Response samples

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

Update a set

Update a set. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
color
string or null
description
string or null

Responses

Request samples

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

Response samples

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

Delete a set

Delete a set; member templates become unassigned. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Variants

Per-template variants and their entity bindings.

List variants

List a template's variants. Requires the read:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "object": "item",
  • "data": [
    ]
}

Create a variant

Create a variant. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
required
string
Array of objects
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "field_schema": [
    ],
  • "binding_config": { }
}

Response samples

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

Get a variant

Fetch a single variant. Requires the read:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
variantId
required
string <uuid>

Responses

Response samples

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

Update a variant

Update a variant. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
variantId
required
string <uuid>
Request Body schema: application/json
required
name
string
Array of objects or null
object or null
sort_order
integer >= 0

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "field_schema": [
    ],
  • "binding_config": { },
  • "sort_order": 0
}

Response samples

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

Delete a variant

Delete a variant (the default variant cannot be deleted). Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
variantId
required
string <uuid>

Responses

Response samples

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

Promote a variant to default

Make a variant the template's default. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
variantId
required
string <uuid>

Responses

Response samples

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

Resolve variant entity bindings

Resolve a variant's entity bindings against the database for a per-slot team selection. Read-only. Requires the read:templates scope. Note that the keys of data.field_values are the template's own field keys and are not snake_cased.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
variant_id
string <uuid>
Array of objects
object
object
league_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
  • "field_schema": [
    ],
  • "slot_selections": { },
  • "fixture_config": { },
  • "league_id": "2a3fad45-7758-4caa-9967-1aff5d77e41a"
}

Response samples

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

Pick a variant by fixture count

Return the variant whose binding_config.fixture.match_count equals count, else the default variant. Requires the read:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
query Parameters
count
required
integer >= 0

Responses

Response samples

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

Destinations

Publishing destinations (S3, Google Drive, email, webhook, social).

List destinations

List publishing destinations. Requires the read:destinations scope. Credentials are never returned; secret fields in config are redacted.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "destinations": [
    ]
}

Create a destination

Create a destination. Requires the admin:org scope. Creatable types today are s3, webhook and email; OAuth-based types are connected through the dashboard.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string
type
required
string (DestinationType)
Enum: "s3" "gdrive" "email" "webhook" "linkedin" "instagram" "facebook" "twitter" "youtube"

Adapter type. Creatable today are s3, webhook and email; others are connected via the dashboard.

object

Non-sensitive config plus any credentials, which are split off and encrypted.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": true,
  • "destination": {
    }
}

Get a destination

Fetch a single destination. Requires the read:destinations scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "destination": {
    }
}

Update a destination

Update a destination. Requires the admin:org scope. config is merged; empty or null values are skipped so existing secrets are preserved.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
object
is_active
boolean

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": true,
  • "destination": {
    }
}

Delete a destination

Delete a destination. Requires the admin:org scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Test a destination config

Test connectivity with an inline config. Requires a valid key. Returns 200 even when the test fails.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
type
required
string (DestinationType)
Enum: "s3" "gdrive" "email" "webhook" "linkedin" "instagram" "facebook" "twitter" "youtube"

Adapter type. Creatable today are s3, webhook and email; others are connected via the dashboard.

required
object

Responses

Request samples

Content type
application/json
{
  • "type": "s3",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "error": "string"
}

Test an existing destination

Test connectivity for a stored destination. Requires a valid key. Returns 200 even when the test fails.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "error": "string"
}

Entities

Sports data - teams, players, leagues, clubs, sports, countries and games.

Get entity counts

Counts of teams, clubs, leagues, sports and players. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

List countries

List countries. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Create a country

Create a country. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string
code
required
string

Stored uppercased.

Responses

Request samples

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

Response samples

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

List sports

List sports. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Create a sport

Create a sport. Requires a valid key.

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

Responses

Request samples

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

Response samples

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

Get a sport

Fetch a single sport. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update a sport

Update a sport. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
icon_url
string

Responses

Request samples

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

Response samples

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

Delete a sport

Delete a sport. Returns 409 if leagues still reference it. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

List leagues

List leagues. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
sport_id
string <uuid>
country_id
string <uuid>
with_counts
string
Enum: "1" "true"

Include team_count per league.

exclude_empty
string
Enum: "1" "true"

Honoured only with with_counts.

Responses

Response samples

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

Create a league

Create a league. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string
abbreviation
string
sport_id
string <uuid>
country_id
string <uuid>
logo_url
string
color
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "abbreviation": "string",
  • "sport_id": "3b33d728-5ec0-45ea-a7eb-bd6133196129",
  • "country_id": "b42f7153-60f9-4aff-a5b5-21576be4161e",
  • "logo_url": "string",
  • "color": "string",
  • "description": "string"
}

Response samples

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

Search leagues

Search leagues by name. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
q
required
string non-empty
limit
integer <= 50
Default: 15

Responses

Response samples

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

Get a league

Fetch a single league. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update a league

Update a league. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
abbreviation
string
logo_url
string
sport_id
string <uuid>
country_id
string <uuid>
color
string
description
string
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "abbreviation": "string",
  • "logo_url": "string",
  • "sport_id": "3b33d728-5ec0-45ea-a7eb-bd6133196129",
  • "country_id": "b42f7153-60f9-4aff-a5b5-21576be4161e",
  • "color": "string",
  • "description": "string",
  • "metadata": { }
}

Response samples

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

Delete a league

Delete a league. Returns 409 if active teams reference it. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

List clubs

List clubs. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
league_id
string <uuid>

Responses

Response samples

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

Create a club

Create a club. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string
league_id
string <uuid>
external_id
string
logo_url
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "league_id": "2a3fad45-7758-4caa-9967-1aff5d77e41a",
  • "external_id": "string",
  • "logo_url": "string"
}

Response samples

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

List teams

List teams. Requires a valid key. With paginated=true the response uses real pagination and adds a top-level total; league_id=none selects league-less teams.

Authorizations:
ApiKeyAuth
query Parameters
club_id
string <uuid>
league_id
string
active
string
Default: "true"
Enum: "true" "false" "all"
sport
string

Sport slug.

country_id
string <uuid>
sport_id
string <uuid>
search
string
limit
integer
Default: 1000
offset
integer
Default: 0
paginated
string
Enum: "1" "true"

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ],
  • "has_more": true,
  • "next_cursor": "string",
  • "total": 0
}

Create a team

Create a team. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string
abbreviation
string

Max 5 characters.

logo_url
string
primary_color
string
secondary_color
string
club_id
string <uuid>
league_id
string <uuid>
set_id
string <uuid>
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": "37075f18-9ac9-4298-acac-03d82cbc40e2",
  • "league_id": "2a3fad45-7758-4caa-9967-1aff5d77e41a",
  • "set_id": "516c4b88-fac0-4d1c-bb7a-9a8534cc5e71",
  • "external_id": "string"
}

Response samples

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

Get team integration coverage

Per-team provider coverage and a summary. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Search teams

Search teams by name or abbreviation. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
q
required
string >= 2 characters
limit
integer <= 100
Default: 20

Responses

Response samples

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

Get a team

Fetch a single team. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update a team

Update a team. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
abbreviation
string
logo_url
string
primary_color
string
secondary_color
string
club_id
string <uuid>
league_id
string <uuid>
set_id
string <uuid>
object
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "abbreviation": "string",
  • "logo_url": "string",
  • "primary_color": "string",
  • "secondary_color": "string",
  • "club_id": "37075f18-9ac9-4298-acac-03d82cbc40e2",
  • "league_id": "2a3fad45-7758-4caa-9967-1aff5d77e41a",
  • "set_id": "516c4b88-fac0-4d1c-bb7a-9a8534cc5e71",
  • "metadata": { },
  • "active": true
}

Response samples

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

Delete a team

Soft-delete a team (sets active=false). Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

List players

List players. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
team_id
string <uuid>
league_id
string <uuid>
active
string
Default: "true"
Enum: "true" "false" "all"
limit
integer
Default: 1000
offset
integer
Default: 0

Responses

Response samples

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

Create a player

Create a player. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
first_name
required
string
last_name
required
string
team_id
required
string <uuid>
jersey_number
integer
position
string
image_url
string
external_player_id
string

Responses

Request samples

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

Response samples

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

Search players

Search players by name, jersey number or team. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
q
required
string >= 2 characters
limit
integer <= 100
Default: 20

Responses

Response samples

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

Get a player

Fetch a single player. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update a player

Update a player. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
first_name
string
last_name
string
jersey_number
integer
position
string
image_url
string
team_id
string <uuid>
external_player_id
string
external_team_id
string
object
active
boolean

Responses

Request samples

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

Response samples

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

Delete a player

Soft-delete a player. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

List games

Read-only schedule access. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
upcoming
string
Default: "true"
Enum: "true" "false"
league_id
string <uuid>
season_id
string
round_nr
string
team_id
string <uuid>
limit
integer <= 50
Default: 10

Responses

Response samples

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

Search games

Search games by competition, league or team. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
q
required
string >= 2 characters
limit
integer <= 50
Default: 15

Responses

Response samples

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

List matchdays

Distinct rounds (matchdays) with kick-off windows. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
league_id
string <uuid>
season_id
string
status
string
Enum: "upcoming" "completed"

Responses

Response samples

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

Get a game

Fetch a single game. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Import entities from CSV

Start an async CSV import of teams or players. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
csv_content
required
string
required
object

Maps system field names to CSV column headers.

entity_type
string
Default: "teams"
Enum: "teams" "players"
object

Responses

Request samples

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

Response samples

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

Get import job status

Poll an import job's status. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
jobId
required
string

Responses

Response samples

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

Download the team import template

Returns a CSV template for team imports. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Download the player import template

Returns a CSV template for player imports. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Data Sources

External data inputs (signed webhooks and pull-based REST sources).

List data sources

List data sources. Requires a valid key. The list also includes enabled integrations as virtual entries with type: INTEGRATION.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Create a data source

Create a data source. Requires an org admin (the admin:org scope for API keys). For WEBHOOK sources a webhook_url is returned. If you omit webhook_secret, a generated secret is returned once as plaintext_webhook_secret; supplying your own is preferred.

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

For REST_GET: endpoint_url (https, required), auth_type (none|bearer|header), auth_header_name.

webhook_secret
string

32-256 url-safe base64 chars. Accepted at the top level or inside config; stripped from stored config.

Responses

Request samples

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

Response samples

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

Get a data source

Fetch a single data source. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update a data source

Update a data source. Requires an org admin (the admin:org scope for API keys).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
object
object

Responses

Request samples

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

Response samples

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

Delete a data source

Soft-delete a data source. Requires an org admin (the admin:org scope for API keys).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Rotate a webhook secret

Rotate the HMAC webhook secret. Requires an org admin (the admin:org scope for API keys). If you omit webhook_secret, a generated secret is returned once.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
webhook_secret
string

Responses

Request samples

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

Response samples

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

Test-ingest a sample payload

Send a sample payload to a data source for schema discovery; the payload becomes the source's sample_payload. Requires an org admin (the admin:org scope for API keys).

Authorizations:
ApiKeyAuth
path Parameters
slug
required
string
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

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

Webhooks

HMAC-signed inbound webhook ingestion that triggers automations.

Ingest a signed webhook

Production webhook ingestion that triggers the automations bound to a data source. This endpoint is NOT authenticated with x-api-key; instead the raw body is signed with the source's HMAC-SHA256 secret. Send the hex signature in one of X-Signature, X-Webhook-Signature or X-Hub-Signature-256. Body cap is 1 MB.

Authorizations:
WebhookSignature
path Parameters
slug
required
string
header Parameters
X-Signature
required
string

HMAC-SHA256 of the raw request body. X-Webhook-Signature or X-Hub-Signature-256 are also accepted.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

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

Automations

Rules that map incoming data-source payloads to templates or workflows.

List automations

List the organization's automations. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Create an automation

Create an automation. New automations start disabled. Requires a valid key.

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

A data-source UUID or integration:<slug>.

target_type
required
string
Enum: "template" "workflow" "multi_template"
template_id
string <uuid>
workflow_id
string <uuid>
template_ids
Array of strings <uuid> [ items <uuid > ]
object

Maps template field ids to source paths, for example {"home_team":"{{source:<id>.match.home}}"}.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "data_source_id": "string",
  • "target_type": "template",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe",
  • "template_ids": [
    ],
  • "mappings": {
    }
}

Response samples

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

Create an automation from an integration

Create an automation for an enabled integration with auto-mapped fields. Requires a valid key. Note that this endpoint takes camelCase body keys.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
integrationType
required
string
templateId
string <uuid>
workflowId
string <uuid>
name
string
object

Responses

Request samples

Content type
application/json
{
  • "integrationType": "string",
  • "templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
  • "workflowId": "43c4fa9b-0cbc-4b57-a121-9d7d46a3eaa4",
  • "name": "string",
  • "customMappings": { }
}

Response samples

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

Get an automation

Fetch a single automation. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update an automation

Update an automation. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
enabled
boolean
object
target_type
string
Enum: "template" "workflow" "multi_template"
template_id
string <uuid>
workflow_id
string <uuid>
template_ids
Array of strings <uuid> [ items <uuid > ]
object
destination_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "mappings": { },
  • "target_type": "template",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe",
  • "template_ids": [
    ],
  • "trigger_config": { },
  • "destination_ids": [
    ]
}

Response samples

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

Delete an automation

Delete an automation. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Flows

The current automation surface, layered over the same engine as automations.

List flows

List the organization's flows. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "object": "flows",
  • "data": [
    ]
}

Create a flow

Create a flow. New flows start disabled. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
string
Default: "Untitled Flow"
description
string
data_source_id
string
target_type
string
Enum: "template" "workflow" "multi_template"
template_id
string <uuid>
workflow_id
string <uuid>
template_ids
Array of strings <uuid> [ items <uuid > ]
object
object
destination_ids
Array of strings <uuid> [ items <uuid > ]
object

Responses

Request samples

Content type
application/json
{
  • "name": "Untitled Flow",
  • "description": "string",
  • "data_source_id": "string",
  • "target_type": "template",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe",
  • "template_ids": [
    ],
  • "mappings": { },
  • "trigger_config": { },
  • "destination_ids": [
    ],
  • "destination_config": { }
}

Response samples

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

Get a flow

Fetch a single flow. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update a flow

Update a flow. Setting status to active enables it. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string
status
string
Enum: "draft" "active" "paused" "error"
object
target_type
string
Enum: "template" "workflow" "multi_template"
template_id
string <uuid>
workflow_id
string <uuid>
template_ids
Array of strings <uuid> [ items <uuid > ]
object
destination_ids
Array of strings <uuid> [ items <uuid > ]
object
data_source_id
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "status": "draft",
  • "mappings": { },
  • "target_type": "template",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe",
  • "template_ids": [
    ],
  • "trigger_config": { },
  • "destination_ids": [
    ],
  • "destination_config": { },
  • "data_source_id": "string"
}

Response samples

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

Delete a flow

Delete a flow. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Activate a flow

Set a flow's status to active. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Pause a flow

Set a flow's status to paused. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Execute a flow

Run a flow once, immediately. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Workflows

Multi-template bundles executed together into a downloadable archive.

List workflows

List the organization's workflows. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
limit
integer
Default: 25
offset
integer
Default: 0

Responses

Response samples

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

Create a workflow

Create a workflow from a set of templates. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string
template_ids
required
Array of strings <uuid> non-empty [ items <uuid > ]
description
string
category
string
object
object
destination_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "template_ids": [
    ],
  • "description": "string",
  • "category": "string",
  • "output_format": { },
  • "shared_fields": { },
  • "destination_ids": [
    ]
}

Response samples

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

Preview merged workflow fields

Preview the merged field schema for a set of templates. Requires a valid key.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
template_ids
required
Array of strings <uuid> non-empty [ items <uuid > ]

Responses

Request samples

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

Response samples

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

Get a workflow

Fetch a single workflow with its field schema. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Update a workflow

Update a workflow. Changing name regenerates the slug. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
template_ids
Array of strings <uuid> [ items <uuid > ]
description
string
category
string
object
object
destination_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "template_ids": [
    ],
  • "description": "string",
  • "category": "string",
  • "output_format": { },
  • "shared_fields": { },
  • "destination_ids": [
    ]
}

Response samples

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

Delete a workflow

Delete a workflow. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Execute a workflow

Execute a workflow with shared field values supplied as multipart form data (text fields and/or files keyed by field name). Returns a ZIP archive of the rendered assets. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
Request Body schema: multipart/form-data
required
property name*
additional property
any

Responses

Response samples

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

Integrations

Third-party data-provider credentials (Magnifi, Spiideo).

List integrations

List configured integrations and the available types. Requires a valid key. Secrets are redacted.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Get an integration

Fetch one integration. Requires a valid key. Secrets are redacted.

Authorizations:
ApiKeyAuth
path Parameters
type
required
string

Responses

Response samples

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

Save an integration

Create or update an integration's credentials. Requires an org admin (the admin:org scope for API keys). magnifi needs accessKey and accessSecret; spiideo needs clientId, clientSecret and userId.

Authorizations:
ApiKeyAuth
path Parameters
type
required
string
Request Body schema: application/json
required
required
object
enabled
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "config": { },
  • "enabled": true
}

Response samples

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

Delete an integration

Delete an integration. Requires an org admin (the admin:org scope for API keys).

Authorizations:
ApiKeyAuth
path Parameters
type
required
string

Responses

Response samples

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

Test an integration

Test integration credentials. Requires a valid key. Returns 200 even when the test fails.

Authorizations:
ApiKeyAuth
path Parameters
type
required
string
Request Body schema: application/json
required
required
object

Responses

Request samples

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

Response samples

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

List integration definitions

Metadata for all available integration types (no secrets). Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Get an integration definition

Metadata for one integration type. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
type
required
string

Responses

Response samples

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

Uploads

Generic asset uploads and signed direct-to-storage URLs.

Upload an asset

Upload a single file (any multipart field name) and receive its public URL. Requires a valid key. Returns a flat { success, url, filename } payload.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "url": "string",
  • "filename": "string"
}

Get a signed upload URL

Get a signed PUT URL for direct browser-to-storage upload. Requires a valid key. The data fields are camelCase.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
filename
string
Default: "asset.bin"
contentType
string

Accepted but currently ignored.

Responses

Request samples

Content type
application/json
{
  • "filename": "asset.bin",
  • "contentType": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Reports

Read-only render reporting (dashboard, weekly, all-time, history, throughput).

Get the dashboard report

Combined weekly, all-time and history report. Requires a valid key. Note the wrapper key allTime is camelCase.

Authorizations:
ApiKeyAuth
query Parameters
weeks
integer <= 52
Default: 8
weekStart
string <date>
weekEnd
string <date>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get the weekly summary

Weekly render summary with week-over-week trend. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
weekStart
string <date>
weekEnd
string <date>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get the all-time report

All-time totals. Requires a valid key.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get the weekly history

Per-week asset counts, oldest to newest. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
weeks
integer <= 52
Default: 8

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get the throughput report

Render throughput over a rolling window. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
days
integer [ 1 .. 90 ]
Default: 7

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Tools

Logo resizing utilities (single and batch).

Start a batch resize

Queue a batch logo resize from storage URLs. Requires a valid key. Returns a camelCase payload.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
sessionId
required
string
logoStorageUrls
required
Array of strings
logoBlobUrls
Array of strings

Legacy alias for logoStorageUrls.

isNationalTeam
boolean

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "logoStorageUrls": [
    ],
  • "logoBlobUrls": [
    ],
  • "isNationalTeam": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "sessionId": "string",
  • "eventId": "string",
  • "message": "string"
}

Upload logos for batch resize

Upload logo files for a batch resize. Requires a valid key. Returns a camelCase payload.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
logoFiles
required
Array of strings <binary> [ items <binary > ]
sessionId
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "sessionId": "string",
  • "logoUrls": [
    ],
  • "uploadedCount": 0
}

Get batch resize status

Poll a batch resize session. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
sessionId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "status": "processing"
}

Fonts

List the organization's fonts

List every font registered for the organization. Requires the read:templates scope. Brand fonts are uploaded once and reused across templates and plugins; at render time a registered font takes precedence over the same Google Fonts family (the designer's exact cut).

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Upload (register) a font

Register a font for the organization. Requires the write:templates scope. Re-uploading the same face (matched by postscript, else family + weight + style) replaces it.

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
font
required
string <binary>

The font file (.ttf, .otf, .woff or .woff2, max 8 MB).

family
required
string
weight
integer
Default: 400
style
string
Default: "normal"
Enum: "normal" "italic"
postscript
string

Exact face identifier (preferred match key).

format
string
Enum: "woff2" "woff" "ttf" "otf"

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organization_id": "string",
  • "family": "Montserrat",
  • "weight": 700,
  • "style": "normal",
  • "postscript_name": "Montserrat-BoldItalic",
  • "format": "woff2",
  • "file_url": "http://example.com",
  • "original_filename": "string",
  • "size_bytes": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove a font

Delete a registered font and its stored file. Requires the write:templates scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deleted": true
}

Download a font's bytes

Serve the raw font file. Requires the read:templates scope. Lets a browser client (e.g. the Figma plugin) fetch a registered font through the API instead of the storage URL directly, avoiding cross-origin restrictions.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

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