{
    "openapi": "3.1.0",
    "info": {
        "title": "FlowData API",
        "version": "v1",
        "description": "API FlowData: geolocalização, informações do cliente, mapas, verificação de e-mail, estatísticas do YouTube e processamento de mídia."
    },
    "servers": [
        {
            "url": "https://api.flowdata.one/v1",
            "description": "FlowData API"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "single-ip",
            "description": "Consulta de IP único"
        },
        {
            "name": "batch",
            "description": "Consulta em lote"
        },
        {
            "name": "endpoint",
            "description": "Endpoint da API"
        },
        {
            "name": "search",
            "description": "Busca de locais"
        },
        {
            "name": "geocoding",
            "description": "Geocodificação"
        },
        {
            "name": "routing",
            "description": "Rotas"
        },
        {
            "name": "endpoints",
            "description": "Endpoints da API"
        },
        {
            "name": "stats",
            "description": "Estatísticas do canal"
        },
        {
            "name": "pipelines",
            "description": "Pipelines e presets"
        },
        {
            "name": "jobs",
            "description": "Jobs"
        },
        {
            "name": "assets",
            "description": "Marcas d'água"
        },
        {
            "name": "callbacks",
            "description": "Callbacks (webhooks)"
        }
    ],
    "paths": {
        "/geolocation": {
            "get": {
                "operationId": "geolocation-client",
                "summary": "Consultar o próprio IP",
                "description": "Identifica o endereço IP do cliente que faz a requisição e responde com seus dados de geolocalização. Somente uma resposta com status: success é cobrada.",
                "tags": [
                    "single-ip"
                ],
                "parameters": [
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Idioma dos rótulos geográficos (padrão de, alternativa en)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "status": "success",
                                    "continent": "Nordamerika",
                                    "continentCode": "NA",
                                    "country": "Vereinigte Staaten",
                                    "countryCode": "US",
                                    "region": "CA",
                                    "regionName": "Kalifornien",
                                    "city": "Mountain View",
                                    "district": null,
                                    "zip": "94043",
                                    "lat": 37.4192,
                                    "lon": -122.0574,
                                    "timezone": "America/Los_Angeles",
                                    "offset": -25200,
                                    "currency": "USD",
                                    "isp": "Google LLC",
                                    "org": "Google LLC",
                                    "as": "AS15169 Google LLC",
                                    "asname": "Google LLC",
                                    "reverse": null,
                                    "mobile": null,
                                    "proxy": null,
                                    "hosting": null,
                                    "query": "8.8.8.8"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/geolocation/{ip}": {
            "get": {
                "operationId": "geolocation-ip",
                "summary": "Consultar um IP ou domínio específico",
                "description": "Consulta dados de geolocalização de um endereço IPv4, IPv6 ou domínio. Somente uma resposta com status: success é cobrada.",
                "tags": [
                    "single-ip"
                ],
                "parameters": [
                    {
                        "name": "ip",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "IPv4, IPv6 ou domínio, por exemplo 8.8.8.8 ou google.com"
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Idioma (padrão de)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/geolocation/batch": {
            "post": {
                "operationId": "geolocation-batch",
                "summary": "Geolocalização em lote",
                "description": "Consulta até 100 endereços IP ou domínios em uma requisição. O corpo da requisição é o próprio array JSON: strings de IP ou objetos no formato {\"query\":\"8.8.8.8\",\"lang\":\"de\"}.",
                "tags": [
                    "batch"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": [
                                    {
                                        "status": "success",
                                        "query": "8.8.8.8",
                                        "country": "Vereinigte Staaten",
                                        "city": "Mountain View"
                                    },
                                    {
                                        "status": "success",
                                        "query": "1.1.1.1",
                                        "country": "Australien",
                                        "city": "Sydney"
                                    }
                                ]
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "maxItems": 100,
                                "items": {
                                    "oneOf": [
                                        {
                                            "type": "string"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "query": {
                                                    "type": "string"
                                                },
                                                "lang": {
                                                    "type": "string"
                                                },
                                                "fields": {
                                                    "type": "string"
                                                }
                                            },
                                            "required": [
                                                "query"
                                            ]
                                        }
                                    ]
                                },
                                "example": [
                                    "8.8.8.8",
                                    "1.1.1.1"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/client-info": {
            "get": {
                "operationId": "client-info-get",
                "summary": "Obter informações do cliente",
                "description": "Lê os cabeçalhos da requisição do cliente e responde com as informações detectadas. Nenhum parâmetro necessário.",
                "tags": [
                    "endpoint"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "ipString": "203.0.113.42",
                                    "ipNumeric": 3405803818,
                                    "ipType": "IPv4",
                                    "isBehindProxy": false,
                                    "device": "Mac",
                                    "os": "Mac OS X 12.6.0",
                                    "userAgent": "Chrome 120.0.0",
                                    "family": "Chrome",
                                    "versionMajor": "120",
                                    "versionMinor": "0",
                                    "versionPatch": "0",
                                    "isSpider": false,
                                    "isMobile": false,
                                    "userAgentDisplay": "Mac OS X 12.6.0 Mac Chrome 120.0.0",
                                    "userAgentRaw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
                                    "userLanguages": [
                                        "de-DE",
                                        "de",
                                        "en-US",
                                        "en"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/maps/search": {
            "get": {
                "operationId": "maps-search",
                "summary": "Buscar endereços e lugares",
                "description": "Busca endereços e lugares. Um resultado já existente é entregue pelo nosso próprio banco de dados, sem consultar um serviço de mapas. Uma busca sem resultado não é cobrada.",
                "tags": [
                    "search"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Termo de busca, até 256 caracteres",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Quantidade de resultados, 1 a 10, padrão 10",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "description": "Filtro de país, ISO 3166-1 alpha-2, por exemplo BR",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "Idioma dos resultados, padrão de",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "proximity",
                        "in": "query",
                        "required": false,
                        "description": "Local preferido como lng,lat",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "types",
                        "in": "query",
                        "required": false,
                        "description": "Tipos de resultado; a requisição vai direto para a Mapbox",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "success": true,
                                    "addresses": [
                                        {
                                            "full_address": "Berlin, Deutschland",
                                            "lat": 52.5200066,
                                            "lng": 13.404954,
                                            "place_name": "Berlin",
                                            "postcode_name": "10115",
                                            "country_name": "Deutschland",
                                            "country_code": "DE"
                                        }
                                    ],
                                    "attribution": "NOTICE: © 2026 FlowSuite and its suppliers. All rights reserved. Use of this data is subject to the Terms of Service (https://creativeskyline.de/agb). This response and the information it contains may not be retained."
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/maps/geocode": {
            "get": {
                "operationId": "maps-geocode",
                "summary": "Resolver endereço ou coordenadas",
                "description": "Transforma um endereço em coordenadas e dados completos de endereço, ou coordenadas de volta em endereço. Somente uma resposta bem-sucedida é cobrada; 404 sem resultado é grátis.",
                "tags": [
                    "geocoding"
                ],
                "parameters": [
                    {
                        "name": "address",
                        "in": "query",
                        "required": false,
                        "description": "Endereço para a busca direta",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "lng",
                        "in": "query",
                        "required": false,
                        "description": "Longitude para a busca reversa, junto com lat",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "lat",
                        "in": "query",
                        "required": false,
                        "description": "Latitude para a busca reversa, junto com lng",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "description": "Filtro de país, ISO 3166-1 alpha-2",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "Idioma dos resultados, padrão de",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "success": true,
                                    "address": {
                                        "full_address": "Friedrichstraße 43, 10117 Berlin, Deutschland",
                                        "lat": 52.5094,
                                        "lng": 13.3889,
                                        "place_name": "Berlin",
                                        "postcode_name": "10117",
                                        "country_name": "Deutschland",
                                        "country_code": "DE"
                                    },
                                    "attribution": "NOTICE: © 2026 FlowSuite and its suppliers. All rights reserved. Use of this data is subject to the Terms of Service (https://creativeskyline.de/agb). This response and the information it contains may not be retained."
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/maps/directions": {
            "get": {
                "operationId": "maps-directions",
                "summary": "Calcular rota",
                "description": "Calcula uma rota entre dois ou mais pontos, com distância, duração e geometria. Somente uma resposta bem-sucedida é cobrada; 404 sem rota é grátis.",
                "tags": [
                    "routing"
                ],
                "parameters": [
                    {
                        "name": "origin",
                        "in": "query",
                        "required": true,
                        "description": "Ponto de partida como lng,lat, por exemplo 13.4050,52.5200",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "destination",
                        "in": "query",
                        "required": true,
                        "description": "Destino como lng,lat",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "profile",
                        "in": "query",
                        "required": false,
                        "description": "driving, driving-traffic, walking ou cycling, padrão driving-traffic",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "waypoints",
                        "in": "query",
                        "required": false,
                        "description": "Paradas como lng,lat, separadas por |",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "Idioma das instruções, padrão de",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "success": true,
                                    "routes": [
                                        {
                                            "distance": 3120.4,
                                            "duration": 540.2,
                                            "legs": [
                                                {
                                                    "distance": 3120.4,
                                                    "duration": 540.2
                                                }
                                            ]
                                        }
                                    ],
                                    "attribution": "NOTICE: © 2026 FlowSuite and its suppliers. All rights reserved. Use of this data is subject to the Terms of Service (https://creativeskyline.de/agb). This response and the information it contains may not be retained."
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/email-verification/{email}": {
            "get": {
                "operationId": "verification",
                "summary": "Verificar um endereço de e-mail",
                "description": "Verifica um endereço de e-mail. result é safe (entregável), risky (entregável, mas incerto), invalid (não entregável) ou unknown (não determinável, não cobrado). reason informa o motivo: accepted, catch_all, role_account, disposable, invalid_syntax, invalid_domain, null_mx, rejected, low_quality, unverifiable, processing_objected (o titular se opôs ao tratamento dos seus dados) ou dns_unavailable. checks contém as verificações individuais (sintaxe, servidor de e-mail, provedor, domínio descartável, endereço de função, catch-all). Os campos anteriores continuam: status é valid se é possível enviar para o endereço, caso contrário risky, invalid, disposable ou unknown. source mostra de onde vem o resultado: DB (resultado armazenado), NA (verificação própria) ou um serviço de verificação (LR, HU, EA). A API responde a um endereço sintaticamente inválido com HTTP 400.",
                "tags": [
                    "endpoints"
                ],
                "parameters": [
                    {
                        "name": "email",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Endereço de e-mail a verificar"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "email_address": "user@example.com",
                                    "status": "valid",
                                    "source": "NA",
                                    "result": "risky",
                                    "reason": "catch_all",
                                    "checks": {
                                        "syntax": true,
                                        "mx": "ok",
                                        "mail_provider": "other",
                                        "disposable": false,
                                        "role_account": false,
                                        "catch_all": true
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/youtube/stats/{identifier}": {
            "get": {
                "operationId": "stats-get",
                "summary": "Obter estatísticas do canal",
                "description": "Consulta as estatísticas de um canal do YouTube. Toda resposta bem-sucedida é cobrada, inclusive com cached: true; 404 para canal não encontrado é grátis.",
                "tags": [
                    "stats"
                ],
                "parameters": [
                    {
                        "name": "identifier",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Handle (por exemplo @YouTube) ou ID do canal (por exemplo UCBR8-60-B28hp2BmDPdntcQ)"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "success": true,
                                    "cached": true,
                                    "data": {
                                        "channel_id": "UCBR8-60-B28hp2BmDPdntcQ",
                                        "handle": "@YouTube",
                                        "title": "YouTube",
                                        "description": "YouTube's official channel...",
                                        "subscriber_count": 40000000,
                                        "video_count": 500,
                                        "view_count": 3000000000,
                                        "thumbnail_url": "https://...",
                                        "last_synced_at": "2026-01-12T10:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/presets": {
            "get": {
                "operationId": "presets-list",
                "summary": "Listar presets",
                "description": "Todas as pipelines do sistema (system: true) e os presets da sua equipe.",
                "tags": [
                    "pipelines"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "data": [
                                        {
                                            "key": "ugc_video",
                                            "system": true,
                                            "pipeline": "ugc_video",
                                            "outputs": [
                                                "watermarked",
                                                "clean",
                                                "thumbnail"
                                            ]
                                        },
                                        {
                                            "key": "ugc_hd",
                                            "system": false,
                                            "name": "UGC in HD",
                                            "pipeline": "ugc_video",
                                            "options": {
                                                "width": 720,
                                                "height": 1280
                                            },
                                            "outputs": {
                                                "clean": {
                                                    "crf": 20
                                                }
                                            },
                                            "updated_at": "2026-09-28T10:00:00Z"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "presets-store",
                "summary": "Criar ou substituir preset",
                "description": "Cria um preset da equipe (201) ou substitui um com a mesma chave (200). Nomes do sistema são reservados.",
                "tags": [
                    "pipelines"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "key": "ugc_hd",
                                    "system": false,
                                    "name": "UGC in HD",
                                    "pipeline": "ugc_video",
                                    "options": {
                                        "width": 720,
                                        "height": 1280,
                                        "watermark": {
                                            "asset": "brand_white",
                                            "opacity": 0.3
                                        }
                                    },
                                    "outputs": {
                                        "clean": {
                                            "crf": 20
                                        }
                                    },
                                    "updated_at": "2026-09-28T10:00:00Z"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "key": {
                                        "type": "string",
                                        "description": "1 a 64 caracteres de a-z, 0-9, _ e -"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Rótulo, no máximo 191 caracteres"
                                    },
                                    "pipeline": {
                                        "type": "string",
                                        "description": "Pipeline base, por exemplo ugc_video"
                                    },
                                    "options": {
                                        "type": "object",
                                        "description": "Opções para todas as saídas, inclusive watermark"
                                    },
                                    "outputs": {
                                        "type": "object",
                                        "description": "Sobrescritas por nome de saída"
                                    }
                                },
                                "required": [
                                    "key",
                                    "pipeline"
                                ]
                            },
                            "example": {
                                "key": "ugc_hd",
                                "name": "UGC in HD",
                                "pipeline": "ugc_video",
                                "options": {
                                    "width": 720,
                                    "height": 1280,
                                    "watermark": {
                                        "asset": "brand_white",
                                        "opacity": 0.3
                                    }
                                },
                                "outputs": {
                                    "clean": {
                                        "crf": 20
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/presets/{key}": {
            "delete": {
                "operationId": "presets-delete",
                "summary": "Excluir preset",
                "description": "Exclui um preset da equipe. Jobs já criados não são afetados, pois têm uma cópia das configurações.",
                "tags": [
                    "pipelines"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "deleted": true,
                                    "key": "ugc_hd"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/jobs": {
            "post": {
                "operationId": "jobs-create",
                "summary": "Criar job",
                "description": "Cria um job e responde com 202 e queue_position. Exatamente um entre pipeline e preset, exatamente um entre input.url e input.upload_id, para cada saída exatamente um entre put_url e managed: true. Todas as URLs devem ser https e apontar para endereços públicos.",
                "tags": [
                    "jobs"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
                                    "status": "queued",
                                    "pipeline": "ugc_video",
                                    "reference": "orderfile:12345",
                                    "priority": "normal",
                                    "outputs": {
                                        "watermarked": {
                                            "status": "pending",
                                            "target": "put"
                                        },
                                        "clean": {
                                            "status": "pending",
                                            "target": "managed",
                                            "download_url": null,
                                            "expires_at": null
                                        },
                                        "thumbnail": {
                                            "status": "pending",
                                            "target": "put"
                                        }
                                    },
                                    "error": null,
                                    "queue_position": 1
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "pipeline": {
                                        "type": "string",
                                        "description": "Pipeline do sistema (ver tabela), alternativa ao preset"
                                    },
                                    "preset": {
                                        "type": "string",
                                        "description": "Chave de um preset da equipe, alternativa à pipeline"
                                    },
                                    "reference": {
                                        "type": "string",
                                        "description": "Sua referência própria (no máximo 191 caracteres), consultável em GET /jobs?reference="
                                    },
                                    "priority": {
                                        "type": "string",
                                        "description": "high, normal (padrão) ou low; course_video é low por padrão"
                                    },
                                    "input": {
                                        "type": "object",
                                        "properties": {
                                            "url": {
                                                "type": "string",
                                                "description": "URL https pública da origem, até 3 redirecionamentos"
                                            },
                                            "upload_id": {
                                                "type": "string",
                                                "description": "ID de POST /uploads, usável uma vez"
                                            },
                                            "filename": {
                                                "type": "string",
                                                "description": "Nome original do arquivo (apenas exibição)"
                                            },
                                            "size": {
                                                "type": "integer",
                                                "description": "Tamanho em bytes; verificado antes contra o limite e melhora a reserva de custo"
                                            }
                                        }
                                    },
                                    "outputs": {
                                        "type": "object",
                                        "properties": {
                                            "<name>.put_url": {
                                                "type": "string",
                                                "description": "URL de PUT pré-assinada para o resultado"
                                            },
                                            "<name>.managed": {
                                                "type": "boolean",
                                                "description": "true: guardamos o resultado por 7 dias"
                                            },
                                            "<name>.content_type": {
                                                "type": "string",
                                                "description": "Content-Type do PUT, padrão conforme o formato"
                                            },
                                            "<name>.*": {
                                                "type": "object",
                                                "description": "Sobrescritas como width, height, fit, crf, format, quality, watermark"
                                            }
                                        }
                                    },
                                    "options": {
                                        "type": "object",
                                        "description": "Opções para todas as saídas, inclusive watermark.asset"
                                    },
                                    "callback": {
                                        "type": "object",
                                        "properties": {
                                            "endpoint_id": {
                                                "type": "string",
                                                "description": "ID de um endpoint de webhook registrado"
                                            },
                                            "url": {
                                                "type": "string",
                                                "description": "URL https livre; assinada com o segredo do endpoint padrão, senão sem assinatura"
                                            },
                                            "events": {
                                                "type": "array",
                                                "items": [],
                                                "description": "job.finished e/ou job.failed (padrão: ambos)"
                                            }
                                        }
                                    },
                                    "metadata": {
                                        "type": "object",
                                        "description": "Qualquer JSON até 4 KB, volta inalterado no callback"
                                    }
                                }
                            },
                            "example": {
                                "pipeline": "ugc_video",
                                "reference": "orderfile:12345",
                                "input": {
                                    "url": "https://files.example.com/in/abc.mov?X-Amz-Signature=…",
                                    "filename": "abc.mov"
                                },
                                "outputs": {
                                    "watermarked": {
                                        "put_url": "https://uploads.example.com/out/wm.mp4?X-Amz-Signature=…"
                                    },
                                    "clean": {
                                        "managed": true
                                    },
                                    "thumbnail": {
                                        "put_url": "https://uploads.example.com/out/thumb.jpg?X-Amz-Signature=…"
                                    }
                                },
                                "options": {
                                    "watermark": {
                                        "asset": "brand_white"
                                    }
                                },
                                "callback": {
                                    "endpoint_id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH"
                                },
                                "metadata": {
                                    "entity": "order_file"
                                }
                            }
                        }
                    }
                }
            },
            "get": {
                "operationId": "jobs-by-reference",
                "summary": "Buscar jobs por referência",
                "description": "Os até 20 jobs mais recentes com esta reference.",
                "tags": [
                    "jobs"
                ],
                "parameters": [
                    {
                        "name": "reference",
                        "in": "query",
                        "required": true,
                        "description": "Sua referência de POST /jobs",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "data": [
                                        {
                                            "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
                                            "status": "finished",
                                            "pipeline": "ugc_video",
                                            "preset": null,
                                            "reference": "orderfile:12345",
                                            "priority": "normal",
                                            "created_at": "2026-09-28T10:00:00Z",
                                            "started_at": "2026-09-28T10:00:02Z",
                                            "finished_at": "2026-09-28T10:00:31Z",
                                            "input": {
                                                "size": 48211234,
                                                "duration": 27.4,
                                                "width": 1080,
                                                "height": 1920,
                                                "video_codec": "hevc",
                                                "has_audio": true
                                            },
                                            "outputs": {
                                                "watermarked": {
                                                    "status": "uploaded",
                                                    "target": "put",
                                                    "size": 6123456,
                                                    "width": 540,
                                                    "height": 960,
                                                    "duration": 27.4,
                                                    "sha256": "9f2c…"
                                                },
                                                "clean": {
                                                    "status": "uploaded",
                                                    "target": "managed",
                                                    "size": 6101234,
                                                    "width": 540,
                                                    "height": 960,
                                                    "duration": 27.4,
                                                    "sha256": "4b1a…",
                                                    "download_url": "https://…",
                                                    "expires_at": "2026-10-05T10:00:31Z"
                                                }
                                            },
                                            "options": {
                                                "watermark": {
                                                    "asset": "brand_white",
                                                    "asset_sha256": "c0ff…"
                                                }
                                            },
                                            "error": null,
                                            "processing_seconds": 28.6,
                                            "cancel_requested": false
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/jobs/{job_id}": {
            "get": {
                "operationId": "jobs-show",
                "summary": "Consultar job",
                "description": "Retorna o job no mesmo formato do callback. Em saídas managed, download_url traz um link assinado válido até expires_at.",
                "tags": [
                    "jobs"
                ],
                "parameters": [
                    {
                        "name": "job_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
                                    "status": "finished",
                                    "pipeline": "ugc_video",
                                    "preset": null,
                                    "reference": "orderfile:12345",
                                    "priority": "normal",
                                    "created_at": "2026-09-28T10:00:00Z",
                                    "started_at": "2026-09-28T10:00:02Z",
                                    "finished_at": "2026-09-28T10:00:31Z",
                                    "input": {
                                        "size": 48211234,
                                        "duration": 27.4,
                                        "width": 1080,
                                        "height": 1920,
                                        "video_codec": "hevc",
                                        "has_audio": true
                                    },
                                    "outputs": {
                                        "watermarked": {
                                            "status": "uploaded",
                                            "target": "put",
                                            "size": 6123456,
                                            "width": 540,
                                            "height": 960,
                                            "duration": 27.4,
                                            "sha256": "9f2c…"
                                        },
                                        "clean": {
                                            "status": "uploaded",
                                            "target": "managed",
                                            "size": 6101234,
                                            "width": 540,
                                            "height": 960,
                                            "duration": 27.4,
                                            "sha256": "4b1a…",
                                            "download_url": "https://…",
                                            "expires_at": "2026-10-05T10:00:31Z"
                                        }
                                    },
                                    "options": {
                                        "watermark": {
                                            "asset": "brand_white",
                                            "asset_sha256": "c0ff…"
                                        }
                                    },
                                    "error": null,
                                    "processing_seconds": 28.6,
                                    "cancel_requested": false
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "operationId": "jobs-cancel",
                "summary": "Cancelar job",
                "description": "Um job em espera vira cancelled imediatamente (sem callback, a reserva é liberada). Um job em andamento recebe um pedido de cancelamento (cancel_requested: true), o worker para em poucos segundos e informa job.failed com error.code = cancelled. Um job encerrado gera 409 conflict.",
                "tags": [
                    "jobs"
                ],
                "parameters": [
                    {
                        "name": "job_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4RD",
                                    "status": "cancelled",
                                    "error": null,
                                    "cancel_requested": false
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/uploads": {
            "post": {
                "operationId": "uploads-create",
                "summary": "Criar upload direto",
                "description": "Para origens sem URL pública: retorna uma URL de PUT pré-assinada no nosso armazenamento. Envie o arquivo para lá e depois use como input.upload_id. Válido por 24 horas, usável uma vez. Por equipe, no máximo oito uploads diretos e 10 GB de tamanho declarado ficam abertos ao mesmo tempo. Um upload continua contando depois de atribuído a um job, até a linha ser removida.",
                "tags": [
                    "jobs"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4UP",
                                    "upload_url": "https://…",
                                    "method": "PUT",
                                    "headers": {
                                        "Content-Type": "video/mp4",
                                        "Content-Length": "734003200"
                                    },
                                    "expires_at": "2026-09-29T10:00:00Z"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "filename": {
                                        "type": "string",
                                        "description": "Nome do arquivo, no máximo 255 caracteres"
                                    },
                                    "size": {
                                        "type": "integer",
                                        "description": "Tamanho em bytes, obrigatório. A URL de PUT pré-assinada assina exatamente este Content-Length; um corpo maior é rejeitado pelo armazenamento."
                                    },
                                    "content_type": {
                                        "type": "string",
                                        "description": "Content-Type que deve ser enviado no PUT"
                                    }
                                },
                                "required": [
                                    "size"
                                ]
                            },
                            "example": {
                                "filename": "kurs-01.mp4",
                                "size": 734003200,
                                "content_type": "video/mp4"
                            }
                        }
                    }
                }
            }
        },
        "/media/usage": {
            "get": {
                "operationId": "usage",
                "summary": "Consultar uso",
                "description": "Jobs, falhas, tempo de processamento e volume de entrada no período (padrão: mês atual). Custos e saldo aparecem no dashboard em Faturamento.",
                "tags": [
                    "jobs"
                ],
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "description": "Data inicial AAAA-MM-DD",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "description": "Data final AAAA-MM-DD",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "from": "2026-09-01",
                                    "to": "2026-09-30",
                                    "jobs": 2143,
                                    "failed": 12,
                                    "processing_seconds": 61234.5,
                                    "input_bytes": 98765432100,
                                    "by_pipeline": {
                                        "ugc_video": 2051,
                                        "ugc_image": 92
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/health": {
            "get": {
                "operationId": "health",
                "summary": "Status",
                "description": "Sem autenticação. ok, degraded (manutenção ou processamento de imagem limitado) ou down, além do tamanho da fila.",
                "tags": [
                    "jobs"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "status": "ok",
                                    "queue": {
                                        "pending": 3,
                                        "processing": 4
                                    },
                                    "version": "1.0.0"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/assets/{key}": {
            "put": {
                "operationId": "assets-put",
                "summary": "Enviar marca d'água",
                "description": "Corpo como PNG bruto (Content-Type: image/png) ou multipart com o campo file. Responde 201 para uma chave nova, 200 para uma nova versão.",
                "tags": [
                    "assets"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "key": "brand_white",
                                    "sha256": "c0ffee…",
                                    "width": 800,
                                    "height": 200,
                                    "size": 18234,
                                    "updated_at": "2026-09-28T10:00:00Z"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "PNG com canal alfa, no máximo 2 MB"
                                    }
                                },
                                "required": [
                                    "file"
                                ]
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "assets-post",
                "summary": "Enviar marca d'água (POST)",
                "description": "Igual ao PUT, para clientes que só enviam multipart com POST.",
                "tags": [
                    "assets"
                ],
                "parameters": [
                    {
                        "name": "key",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "key": "brand_white",
                                    "sha256": "c0ffee…",
                                    "width": 800,
                                    "height": 200,
                                    "size": 18234,
                                    "updated_at": "2026-09-28T10:00:00Z"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "PNG com canal alfa, no máximo 2 MB"
                                    }
                                },
                                "required": [
                                    "file"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/media/assets": {
            "get": {
                "operationId": "assets-list",
                "summary": "Listar marcas d'água",
                "description": "Todas as marcas d'água da sua equipe com a versão atual.",
                "tags": [
                    "assets"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "data": [
                                        {
                                            "key": "brand_white",
                                            "sha256": "c0ffee…",
                                            "width": 800,
                                            "height": 200,
                                            "size": 18234,
                                            "updated_at": "2026-09-28T10:00:00Z"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/webhook-endpoints": {
            "get": {
                "operationId": "webhook-endpoints-list",
                "summary": "Listar endpoints",
                "description": "Todos os endpoints da sua equipe, sem o segredo.",
                "tags": [
                    "callbacks"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "data": [
                                        {
                                            "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
                                            "url": "https://example.com/hooks/media",
                                            "description": null,
                                            "events": [
                                                "job.finished",
                                                "job.failed"
                                            ],
                                            "is_default": true,
                                            "active": true,
                                            "previous_secret_expires_at": null,
                                            "created_at": "2026-09-28T10:00:00Z"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "webhook-endpoints-create",
                "summary": "Criar endpoint",
                "description": "Cria um endpoint e retorna o segredo uma única vez no campo secret. is_default: true retira a marcação de outro endpoint.",
                "tags": [
                    "callbacks"
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
                                    "url": "https://example.com/hooks/media",
                                    "events": [
                                        "job.finished",
                                        "job.failed"
                                    ],
                                    "is_default": true,
                                    "active": true,
                                    "secret": "whsec_BEISPIEL00000000000000000000000"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "description": "URL https pública"
                                    },
                                    "events": {
                                        "type": "array",
                                        "items": [],
                                        "description": "job.finished e/ou job.failed (padrão: ambos)"
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "No máximo 191 caracteres"
                                    },
                                    "is_default": {
                                        "type": "boolean",
                                        "description": "Também assina callback.url livre"
                                    }
                                },
                                "required": [
                                    "url"
                                ]
                            },
                            "example": {
                                "url": "https://example.com/hooks/media",
                                "events": [
                                    "job.finished",
                                    "job.failed"
                                ],
                                "is_default": true
                            }
                        }
                    }
                }
            }
        },
        "/media/webhook-endpoints/{endpoint_id}/rotate-secret": {
            "post": {
                "operationId": "webhook-endpoints-rotate",
                "summary": "Renovar segredo",
                "description": "Cria um novo segredo e o retorna uma vez. O antigo continua assinando por 24 horas (previous_secret_expires_at).",
                "tags": [
                    "callbacks"
                ],
                "parameters": [
                    {
                        "name": "endpoint_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH",
                                    "previous_secret_expires_at": "2026-09-29T10:00:00Z",
                                    "secret": "whsec_…"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/media/webhook-endpoints/{endpoint_id}": {
            "delete": {
                "operationId": "webhook-endpoints-delete",
                "summary": "Excluir endpoint",
                "description": "Exclui o endpoint. Entregas abertas para ele são abandonadas.",
                "tags": [
                    "callbacks"
                ],
                "parameters": [
                    {
                        "name": "endpoint_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "deleted": true,
                                    "id": "01J8Z6Q4T0M3S1V7B2X9K5N4WH"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Chave FlowData como Authorization: Bearer fd_…"
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "message": {
                                "type": "string"
                            },
                            "type": {
                                "type": "string"
                            },
                            "details": {
                                "type": "object"
                            }
                        }
                    }
                }
            }
        }
    }
}