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 (max 100 per request) 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. An array with more than 100 items returns 400.

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
standings_league_id
string

League id for a standings render. Stamps jobs.league_id on the persisted job so a team-less league asset can auto-populate the League Hub.

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>
output_format
string
Default: "png"
Enum: "png" "pdf"

pdf emits a print-ready PDF/X-4 instead of a PNG: the render is rasterised at the template's print resolution (default 300 DPI, per-template print_config.dpi) with supersampled anti-aliasing (see print_config.supersample), separated to CMYK and delivered with an embedded ISO Coated v2 300% (FOGRA39) output intent. HTML templates only; requires the pdf_export feature flag, otherwise the value is ignored.

Responses

Request samples

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

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

Publish multiple jobs

Publish a set of completed jobs to the same destinations in one request. Requires the write:jobs scope.

Like the single-job publish endpoint this only enqueues the work and answers 202; delivery happens asynchronously. Jobs that cannot be published are not an error - they come back under skipped with a reason (not_found, not_completed, no_output), where not_found also covers ids belonging to another organization.

Poll /api/v1/jobs/publish-status for the per-destination outcome.

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

Responses

Request samples

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

Response samples

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

Publish outcome for a set of jobs

Per-destination publish result for up to 100 jobs. Requires the read:jobs scope.

publish_status stays null until the asynchronous publish has finished, which makes this the honest answer to "did it publish?" - the publish endpoints themselves only ever confirm that the work was queued. A job published earlier still carries the record of that run, so compare published_at against what the job had before you queued.

Authorizations:
ApiKeyAuth
query Parameters
ids
required
string

Comma-separated job ids (max 100).

Responses

Response samples

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

Download several jobs as one ZIP

Streams a single ZIP archive of the selected completed jobs, built server-side. Each single-asset job becomes one entry named after its title; a batch job expands to its per-render assets under a folder. Unreachable assets are skipped rather than failing the whole archive. Requires the read:jobs scope.

Authorizations:
ApiKeyAuth
query Parameters
ids
required
string

Comma-separated job ids (max 100).

Responses

Response samples

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

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>.

set
string

Set id — only runs whose template belongs to that set. Pass none for templates that belong to no set. Runs without a template (reels, workflow runs) are excluded whenever this filter is set.

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, template and set 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": {
    }
}

Download the rendered asset

Redirects to a short-lived signed URL that serves the asset as an attachment, named after the asset's title. Follow the redirect to receive the file. Batch jobs redirect to the batch ZIP endpoint. Requires the read:jobs scope.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

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. Requires write:jobs. Provide exactly one row source:

  • rows - CSV source: each row carries pre-resolved <field>_url values (upload logos first via /api/v1/batch/get-upload-link).
  • league_id / team_ids - "Select League" source: the server expands the league's active teams (or an explicit team_ids subset) into rows (single-team templates). Mutually exclusive with rows.
  • game_ids - "Select Matchday" source: the server expands the given games into home-vs-away rows (matchup templates), resolving logos / colors / names / score / kickoff from the DB. Org-scoped; foreign ids are dropped. Mutually exclusive with rows and with the league source.

This endpoint returns a raw { data } payload (no object wrapper).

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

CSV source. One object per asset; carries <field>_url values. Legacy alias variants is accepted. Mutually exclusive with league_id.

league_id
string <uuid>

"Select League" source. Renders the whole league (its active teams) x the selected variants. Mutually exclusive with rows.

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

"Select League" source, refined. Render exactly these teams (pick / deselect). Org-scoped; foreign ids are dropped. Wins over league_id. Mutually exclusive with rows.

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

"Select Matchday" source. Render exactly these games as home-vs-away rows (matchup templates). Org-scoped; foreign ids are dropped. Mutually exclusive with rows and with league_id / team_ids.

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

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

name_column
string
Default: ""
output_format
string
Default: "png"
Enum: "png" "pdf"

pdf renders every asset of the batch as a print-ready PDF/X-4 (300 DPI raster with supersampled anti-aliasing, CMYK, embedded ISO Coated v2 300% / FOGRA39 output intent) instead of PNG. HTML templates only; requires the pdf_export feature flag, otherwise the value is ignored.

Responses

Request samples

Content type
application/json
{
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "rows": [
    ],
  • "league_id": "2a3fad45-7758-4caa-9967-1aff5d77e41a",
  • "team_ids": [
    ],
  • "game_ids": [
    ],
  • "variant_ids": [
    ],
  • "name_column": "",
  • "output_format": "png"
}

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

Download a batch as ZIP

Streams a ZIP of all successfully rendered batch assets, built on demand from the per-render asset URLs. Multi-team batches are grouped into one folder per team; every file is named <team>_<template>_<variant>.<ext>. Legacy batches that stored a combined ZIP are redirected (302) to it. Requires read:jobs.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

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
template_purpose
string or null
Enum: "reel_intro" "reel_lower_third" "reel_outro"

Reel role tag so a template can serve as a reel intro or lower-third. Send null to clear it.

manual_minutes
integer or null >= 0

Estimated minutes to hand-make one asset from this template; drives the Time Saved figure. Send null to clear.

object or null (PrintConfig)

Print export settings for output_format: pdf renders (PDF/X-4 CMYK). Stored per template; snapshotted onto jobs at creation. Pass null to clear.

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,
  • "template_purpose": "reel_intro",
  • "manual_minutes": 0,
  • "print_config": {
    }
}

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

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

Feature Flags

Per-organization feature rollout toggles.

List feature flags

List the org's feature flags with resolved state. Descriptions and management fields are platform-admin only.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Toggle a feature flag

Set a feature flag. Platform super-admin only. scope 'global' sets the registry default (for all orgs); otherwise a per-org override for the caller's org.

Authorizations:
ApiKeyAuth
path Parameters
key
required
string

The feature flag key.

Request Body schema: application/json
required
enabled
required
boolean
scope
string
Default: "org"
Enum: "org" "global"

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "object": "feature_flag",
  • "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": {
    }
}

Activate (go live) a variant version

Pin the variant's active version (active_version_id) to the given version — this takes a DRAFT variant (no active version, e.g. one created from chat / Figma) live. 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>

The variant-scoped version to make active.

Responses

Request samples

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

Response samples

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

Get the field-binding vocabulary

The entity/slot/role vocabulary for template field bindings — the server-owned source of truth the Build Page binding editor builds its dropdowns from. Static and org-agnostic. Read-only. Requires the read:templates scope. Roles carry applies_to (the entities a role is canonical for; an empty list is a content/metadata role). sponsor roles are dynamic (Club Hub brand-asset slots) and are NOT listed here — the client loads them org-scoped separately.

Authorizations:
ApiKeyAuth

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
object

Standings auto-fill (feature flag standings_binding). Fills a table template's per-position fields (position_N groups) from the current league standings. The source follows the league registration: a football league tagged for the Swiss FA is read live from the federation ranking, every other league from SHV pregame data. Per position the resolver fills the fields whose key contains team_logo, team_name, games, points, goals_for, goals_against or goals (combined, e.g. "41:12"). Entity and league resolution still run alongside it and merge, so a table template's league roles and a flow_round field (from the current matchday, reported as meta.standings.round_nr) resolve too; the standings fill wins for its per-position keys.

object

Top scorer auto-fill (feature flag topscorer_binding). Fills a leaderboard template's per-position fields (position_N groups) from the current league top scorers (SHV group feed; handball only). Per position the resolver fills the fields whose key contains player_name (player_first_name/player_last_name), player_photo/player_portrait or player_headshot/player_image (image contract: key=null + <key>_url), team_logo, team_name, goals, goals_per_game, goals_7m, games or rank. Entity and league resolution still run alongside it and merge; the top-scorer fill wins for its per-position keys.

league_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
  • "field_schema": [
    ],
  • "slot_selections": { },
  • "fixture_config": { },
  • "standings_config": {
    },
  • "topscorer_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. Types your organization is not enabled for are rejected with 403.

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" "spiideo"

Adapter type. Creatable today are s3, webhook and email; others are connected via the dashboard. spiideo delivers rendered assets into a Spiideo account's asset library and is only offered to organizations the feature is enabled for.

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" "spiideo"

Adapter type. Creatable today are s3, webhook and email; others are connected via the dashboard. spiideo delivers rendered assets into a Spiideo account's asset library and is only offered to organizations the feature is enabled for.

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
logo_on_light_url
string

Logo version for light/white surfaces.

logo_on_dark_url
string

Logo version for dark surfaces.

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",
  • "logo_on_light_url": "string",
  • "logo_on_dark_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
league_id
string <uuid>

Scope the search to one league (picker cascade).

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
logo_on_light_url
string or null

Logo version for light/white surfaces. Send null to clear it.

logo_on_dark_url
string or null

Logo version for dark surfaces. Send null to clear it.

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",
  • "logo_on_light_url": "string",
  • "logo_on_dark_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": {
    }
}

Get a team's live roster and stats

Roster plus player/goalie season stats, fetched live from Hockeydata (German/Austrian ice hockey) and never stored. Only works for teams whose league is mapped to Hockeydata; other teams return source: null with empty arrays. During pre-season the most recent season with a filled roster is returned (see season_name). Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "object": "roster",
  • "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
team_id
string <uuid>

Scope the search to a single team's roster.

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" "all"

all drops the time filter (both played and upcoming) - needed to list a whole matchday.

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) of ONE season with kick-off windows. Requires a valid key. Pass group to scope the counts to one league sub-group. Without season_id the newest season that has rounds is used.

Authorizations:
ApiKeyAuth
query Parameters
league_id
string <uuid>
season_id
string

Season to list, from /games/seasons. Omit for the newest season with rounds.

group
string

League sub-group label (teams.group_label), e.g. 1, 2 or 3.

Responses

Response samples

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

List seasons

Seasons a league has games for, newest first. season_id is provider-specific (Sportradar stores the start year of 2026/27, the SFV the end year), so each entry carries a label derived from its kick-off range plus the providers it came from. Requires a valid key.

Authorizations:
ApiKeyAuth
query Parameters
league_id
string <uuid>
group
string

League sub-group label (teams.group_label), e.g. 1, 2 or 3.

Responses

Response samples

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

List a league's sub-groups

Distinct sub-group labels (teams.group_label) present in the league (e.g. "1", "2", "3" for 1. Liga Classic). Empty when the league has no groups. Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

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

Get the live league table

Current league table, fetched live from the league's data source (SHV group feed, SFV ranking, or Hockeydata for German/Austrian ice hockey — resolved from the league row) and never stored. Ice hockey rows additionally carry OT wins/losses and points per game. During pre-season the most recent completed season's table is returned (see season_name). Requires a valid key.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string
query Parameters
group
string

Sub-group filter — SFV group id, or a Hockeydata division name substring (e.g. "Ost").

limit
integer [ 1 .. 50 ]
Default: 50

Max table rows.

Responses

Response samples

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

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

Import a league roster (structured)

Create a league and its teams from structured rows (the hybrid League Import UI), rather than raw CSV. Provide either an existing league.id (add to it) or a league.name to get-or-create. Team logos must already be uploaded via POST /api/v1/upload-asset, so each team carries a logo_url. Runs async on the same job store as the CSV import; poll GET /api/v1/entities/import/status/{jobId}. Gated by the league_import feature flag (403 when off). Requires a valid key.

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

Existing league by id, or a new one by name.

required
Array of objects <= 1000 items
object

Responses

Request samples

Content type
application/json
{
  • "league": {
    },
  • "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. enabled decides whether it runs.

status is accepted for backwards compatibility and mapped onto enabled (active enables, anything else disables); an explicit enabled in the same body wins. It is no longer stored or returned.

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

Whether the flow runs.

status
string
Deprecated
Enum: "draft" "active" "paused" "error"

Legacy alias - mapped onto enabled, never stored. Send enabled instead.

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",
  • "enabled": true,
  • "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 scheduled work

Every scheduled sync and scheduled render the organization owns, across all integrations, each with a health verdict. Integrations the organization is not entitled to are omitted rather than rejected.

Use this for a dashboard view. To change a schedule, go through the per-integration routes.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

List one integration's schedules

Every schedule under this integration. league_name and template_names are resolved server-side so a render schedule states what it renders, not only when.

Authorizations:
ApiKeyAuth
path Parameters
integrationId
required
string

shv, sportradar, heimspiel, sfv, spiideo, or matchday for scheduled renders.

Responses

Response samples

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

Create a scheduled render

Only scheduled renders can be created here, and only under the matchday integration — the data-pull schedules are seeded when their integration is enabled. next_run_at is derived from the cron and is never accepted from a client.

Authorizations:
ApiKeyAuth
path Parameters
integrationId
required
string

shv, sportradar, heimspiel, sfv, spiideo, or matchday for scheduled renders.

Request Body schema: application/json
required
job_type
required
string
Enum: "matchday_render" "standings_render"
cron_expr
required
string

Standard 5-field cron, interpreted as UTC.

league_id
required
string <uuid>
template_ids
Array of strings <uuid> [ items <uuid > ]

At least one. template_id is accepted as a single-value alias.

template_id
string <uuid>
window_mode
required
string
Enum: "upcoming" "past"
window_days
integer or null [ 0 .. 14 ]

matchday_render only: how far the window reaches, in days from the day the schedule runs; window_mode gives the direction. Omit or send null for the default (2 forward, 3 back), which covers the weekend from a Friday or Monday run. A Tuesday run with 2 covers the midweek games instead.

group_label
string or null
destination_ids
Array of strings <uuid> [ items <uuid > ]
destination_folder
string or null
display_name
string <= 80 characters

Optional name for the schedule. Omitted, the name is derived from the job type.

Responses

Request samples

Content type
application/json
{
  • "job_type": "matchday_render",
  • "cron_expr": "0 8 * * 5",
  • "league_id": "2a3fad45-7758-4caa-9967-1aff5d77e41a",
  • "template_ids": [
    ],
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "window_mode": "upcoming",
  • "window_days": 14,
  • "group_label": "string",
  • "destination_ids": [
    ],
  • "destination_folder": "string",
  • "display_name": "string"
}

Response samples

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

Update a schedule

Every field is optional; only what is sent is changed. Changing cron_expr recomputes next_run_at.

The render-config half (league_id, template_ids, window_mode, window_days, group_label, destination_ids, destination_folder) is rejected with 400 on job types that have no render configuration, rather than silently ignored. group_label, destination_folder and an empty destination_ids clear the stored value.

label is not patchable: it is part of the uniqueness key the seeder de-duplicates on. Use display_name to rename a schedule.

Authorizations:
ApiKeyAuth
path Parameters
integrationId
required
string
id
required
string <uuid>
Request Body schema: application/json
required
cron_expr
string
enabled
boolean
display_name
string <= 80 characters

Empty string resets to the name derived from the job type.

team_filter
Array of strings
league_id
string <uuid>
template_ids
Array of strings <uuid> non-empty [ items <uuid > ]
window_mode
string
Enum: "upcoming" "past"
window_days
integer or null [ 0 .. 14 ]

How far the window reaches, in days from the run day. null resets to the default (2 forward, 3 back).

group_label
string or null
destination_ids
Array of strings <uuid> [ items <uuid > ]
destination_folder
string or null

Responses

Request samples

Content type
application/json
{
  • "cron_expr": "0 8 * * 5",
  • "enabled": true,
  • "display_name": "string",
  • "team_filter": [
    ],
  • "league_id": "2a3fad45-7758-4caa-9967-1aff5d77e41a",
  • "template_ids": [
    ],
  • "window_mode": "upcoming",
  • "window_days": 14,
  • "group_label": "string",
  • "destination_ids": [
    ],
  • "destination_folder": "string"
}

Response samples

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

Delete a scheduled render

Only scheduled renders (matchday_render, standings_render) can be deleted. A data-pull schedule is seeded whenever its integration is enabled, so deleting one would only hide it until the next reseed — disable it instead. Assets the schedule already rendered are untouched.

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

Responses

Response samples

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

Run a schedule now

Queue the schedule immediately, out of band. Deliberately forced: the run happens even when a job for the same matchday already exists, which is the point after a data fix. next_run_at is left alone.

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

Responses

Response samples

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

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

Get insight-lane lines

Human-readable insight lines for a page's insight lane. Requires a valid key. Unknown areas fall back to 'runs'.

Authorizations:
ApiKeyAuth
query Parameters
area
string
Default: "runs"
Enum: "runs" "hub" "build" "library"

Responses

Response samples

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

Get estimated time saved

Estimated hand-editing time the render engine replaced, from each template's user-entered manual_minutes (asset-aware). Reports the savings within the requested window plus a constant all-time anchor. Requires a valid key. has_estimates is false until at least one template is estimated.

Authorizations:
ApiKeyAuth
query Parameters
created_after
string <date-time>

Lower bound of the reporting window (ISO 8601). The window figures cover created_after..now; omit for all-time.

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