{ "openapi": "3.1.1", "info": { "title": "Unite Research API", "version": "1.0.0", "description": "Public read-only access to the 19 published charts and 248 aggregate rows of Benchmark Criativo Black Friday Brasil 2026. No authentication or payment required. Values retain their original Portuguese display formatting; preserve each chart comparison and period. Errors use RFC 9457 problem details. HEAD and OPTIONS are also supported. URL path versioning uses /api/v1; API-Version response header is 1.0.0. GET/HEAD/OPTIONS are idempotent read operations; no Idempotency-Key is needed because the API has no writes. Cursor pagination binds the next page to the same query and dataset revision. SDKs JavaScript/TypeScript, Python e CLI: https://github.com/ZupTech/unite-research-sdk . Política de versões e depreciação: https://research.unitebr.com/api-policy . Limite no firewall: 300 requisições por IP/60 segundos por região.", "contact": { "name": "Unite Research", "url": "https://research.unitebr.com/contact", "email": "support@myunite.ai" }, "license": { "name": "Reuse of published study numbers and charts with attribution", "url": "https://research.unitebr.com/benchmark-criativo-black-friday-brasil-2026#citar" } }, "servers": [ { "url": "https://research.unitebr.com", "description": "Production" } ], "security": [], "tags": [ { "name": "Research", "description": "Published study data and citations" } ], "externalDocs": { "url": "https://research.unitebr.com/developers", "description": "Quickstart, examples, pagination, errors and caching" }, "paths": { "/api/v1/charts": { "get": { "operationId": "listCharts", "summary": "Find charts by topic and retrieve metadata", "description": "Find charts by topic and retrieve metadata Public, read-only; no authentication required.", "tags": [ "Research" ], "security": [], "parameters": [ { "name": "query", "in": "query", "description": "Match title, comparison, period and column labels, ignoring case and accents.", "schema": { "type": "string", "maxLength": 160 } }, { "name": "offset", "in": "query", "description": "Zero-based offset. Follow next_offset until null.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum items per page, from 1 to 50. Default is 10 for lists and 20 for chart rows.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque next_cursor from the previous response. Preferred pagination; use instead of offset. Invalid or stale cursors return 400.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Successful public read", "headers": { "ETag": { "description": "Content validator. Send If-None-Match on subsequent requests.", "schema": { "type": "string" } }, "Access-Control-Allow-Origin": { "description": "Public data permits cross-origin reads.", "schema": { "type": "string", "const": "*" } }, "API-Version": { "description": "Current API contract version. Legacy unversioned routes remain aliases of v1.", "schema": { "type": "string", "const": "1.0.0" } }, "RateLimit-Limit": { "description": "Configured firewall request limit per IP and region.", "schema": { "type": "integer", "const": 300 } }, "RateLimit-Policy": { "description": "Configured fixed-window policy, not a remaining balance.", "schema": { "type": "string", "const": "300;w=60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartList" } } } }, "304": { "description": "Unchanged response for If-None-Match." }, "400": { "description": "Invalid query parameters. Correct detail before retrying.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Chart or endpoint not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Firewall rate limit exceeded: 300 requests per IP per 60-second fixed window, per region. Wait at least 60 seconds if Retry-After is absent.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "externalDocs": { "url": "https://research.unitebr.com/developers" } } }, "/api/v1/charts/{chart_id}": { "get": { "operationId": "getChartData", "summary": "Read chart values, comparison, period, population and source", "description": "Read chart values, comparison, period, population and source Public, read-only; no authentication required.", "tags": [ "Research" ], "security": [], "parameters": [ { "name": "chart_id", "in": "path", "required": true, "description": "Chart ID obtained from listCharts.", "schema": { "type": "string", "enum": [ "ch-hook", "ch-opp", "ch-bfmenu", "ch-bfhow", "ch-bfdur", "ch-place", "ch-ret", "ch-bflaunch", "ch-read", "ch-zero", "ch-bfday", "ch-bfweek", "ch-bfdates", "ch-bframp", "ch-bfsplit", "ch-scale", "ch-bffreq", "ch-bfpost", "ch-bfplan" ] } }, { "name": "offset", "in": "query", "description": "Zero-based offset. Follow next_offset until null.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "description": "Maximum items per page, from 1 to 50. Default is 10 for lists and 20 for chart rows.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque next_cursor from the previous response. Preferred pagination; use instead of offset. Invalid or stale cursors return 400.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Successful public read", "headers": { "ETag": { "description": "Content validator. Send If-None-Match on subsequent requests.", "schema": { "type": "string" } }, "Access-Control-Allow-Origin": { "description": "Public data permits cross-origin reads.", "schema": { "type": "string", "const": "*" } }, "API-Version": { "description": "Current API contract version. Legacy unversioned routes remain aliases of v1.", "schema": { "type": "string", "const": "1.0.0" } }, "RateLimit-Limit": { "description": "Configured firewall request limit per IP and region.", "schema": { "type": "integer", "const": 300 } }, "RateLimit-Policy": { "description": "Configured fixed-window policy, not a remaining balance.", "schema": { "type": "string", "const": "300;w=60" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartData" } } } }, "304": { "description": "Unchanged response for If-None-Match." }, "400": { "description": "Invalid query parameters. Correct detail before retrying.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Chart or endpoint not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Firewall rate limit exceeded: 300 requests per IP per 60-second fixed window, per region. Wait at least 60 seconds if Retry-After is absent.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "externalDocs": { "url": "https://research.unitebr.com/developers" } } }, "/api/v1/citation": { "get": { "operationId": "getCitation", "summary": "Read study citation, methodology, limitations and reuse terms", "description": "Read study citation, methodology, limitations and reuse terms Public, read-only; no authentication required.", "tags": [ "Research" ], "security": [], "parameters": [ { "name": "chart_id", "in": "query", "description": "Optional chart ID to include its specific comparison, period and population.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful public read", "headers": { "ETag": { "description": "Content validator. Send If-None-Match on subsequent requests.", "schema": { "type": "string" } }, "Access-Control-Allow-Origin": { "description": "Public data permits cross-origin reads.", "schema": { "type": "string", "const": "*" } }, "API-Version": { "description": "Current API contract version. Legacy unversioned routes remain aliases of v1.", "schema": { "type": "string", "const": "1.0.0" } }, "RateLimit-Limit": { "description": "Configured firewall request limit per IP and region.", "schema": { "type": "integer", "const": 300 } }, "RateLimit-Policy": { "description": "Configured fixed-window policy, not a remaining balance.", "schema": { "type": "string", "const": "300;w=60" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "citation" ], "properties": { "ok": { "type": "boolean" }, "citation": { "$ref": "#/components/schemas/Citation" } } } } } }, "304": { "description": "Unchanged response for If-None-Match." }, "400": { "description": "Invalid query parameters. Correct detail before retrying.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Chart or endpoint not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Firewall rate limit exceeded: 300 requests per IP per 60-second fixed window, per region. Wait at least 60 seconds if Retry-After is absent.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "externalDocs": { "url": "https://research.unitebr.com/developers" } } }, "/api/v1/health": { "get": { "operationId": "getHealth", "summary": "Check API availability and dataset version", "description": "Check API availability and dataset version Public, read-only; no authentication required.", "tags": [ "Research" ], "security": [], "parameters": [], "responses": { "200": { "description": "Successful public read", "headers": { "ETag": { "description": "Content validator. Send If-None-Match on subsequent requests.", "schema": { "type": "string" } }, "Access-Control-Allow-Origin": { "description": "Public data permits cross-origin reads.", "schema": { "type": "string", "const": "*" } }, "API-Version": { "description": "Current API contract version. Legacy unversioned routes remain aliases of v1.", "schema": { "type": "string", "const": "1.0.0" } }, "RateLimit-Limit": { "description": "Configured firewall request limit per IP and region.", "schema": { "type": "integer", "const": 300 } }, "RateLimit-Policy": { "description": "Configured fixed-window policy, not a remaining balance.", "schema": { "type": "string", "const": "300;w=60" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "dataset_version", "chart_count", "row_count" ], "properties": { "status": { "type": "string", "const": "ok" }, "dataset_version": { "type": "string" }, "chart_count": { "type": "integer" }, "row_count": { "type": "integer" } } } } } }, "304": { "description": "Unchanged response for If-None-Match." }, "400": { "description": "Invalid query parameters. Correct detail before retrying.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Chart or endpoint not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "Only GET, HEAD and OPTIONS are supported.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Firewall rate limit exceeded: 300 requests per IP per 60-second fixed window, per region. Wait at least 60 seconds if Retry-After is absent.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "externalDocs": { "url": "https://research.unitebr.com/developers" } } } }, "components": { "schemas": { "Chart": { "type": "object", "required": [ "chart_id", "title", "comparison", "period_and_population", "columns", "row_count" ], "properties": { "chart_id": { "type": "string" }, "title": { "type": "string" }, "comparison": { "type": "string" }, "period_and_population": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "row_count": { "type": "integer", "minimum": 1 } } }, "Citation": { "type": "object", "required": [ "source", "title", "canonical_url", "methodology", "published", "modified" ], "properties": { "source": { "type": "string" }, "title": { "type": "string" }, "canonical_url": { "type": "string" }, "markdown_url": { "type": "string" }, "published": { "type": "string" }, "modified": { "type": "string" }, "attribution": { "type": "string" }, "methodology": { "type": "string" }, "methodology_url": { "type": "string" }, "interpretation": { "type": "string" }, "independence": { "type": "string" }, "reuse": { "type": "string" } } }, "ChartList": { "type": "object", "required": [ "ok", "total", "offset", "next_offset", "items", "next_cursor" ], "properties": { "ok": { "type": "boolean", "const": true }, "total": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "next_offset": { "type": [ "integer", "null" ], "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Chart" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque continuation cursor for the same query and dataset revision." } } }, "ChartData": { "type": "object", "required": [ "ok", "total", "offset", "next_offset", "items", "chart", "citation", "next_cursor" ], "properties": { "ok": { "type": "boolean", "const": true }, "total": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "next_offset": { "type": [ "integer", "null" ], "minimum": 0 }, "items": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "chart": { "$ref": "#/components/schemas/Chart" }, "citation": { "$ref": "#/components/schemas/Citation" }, "value_format": { "type": "string" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque continuation cursor for the same query and dataset revision." } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "detail", "instance" ], "properties": { "type": { "type": "string", "format": "uri-reference" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } } } } } }