{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/typesearch-ai/json-schema/typesearch-ai-chart-schema.json", "title": "Chart", "x-generated": "2026-10-31", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/typesearch-ai-api-v1-openapi.json#/components/schemas/Chart", "type": "object", "properties": { "id": { "description": "chart_…; null with store: false or plan_only.", "type": [ "string", "null" ] }, "object": { "type": "string", "const": "chart" }, "type": { "anyOf": [ { "type": "string", "enum": [ "line", "area", "bar", "bar_horizontal", "stacked_bar", "pie", "donut", "scatter", "funnel", "timeline", "kpi", "table" ] }, { "type": "null" } ] }, "theme": { "type": "string", "enum": [ "light", "dark", "editorial", "electric" ] }, "locale": { "type": "string", "enum": [ "en", "es" ] }, "chart": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "line", "area", "bar", "bar_horizontal", "stacked_bar", "pie", "donut", "scatter", "funnel", "timeline", "kpi", "table" ] }, "title": { "type": "string", "description": "States the finding: «The blue dollar rose 4.1% this week»." }, "subtitle": { "type": "string" }, "x": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "time", "category", "number" ] }, "label": { "type": "string" }, "unit": { "type": "string" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month", "year" ] } }, "required": [ "kind" ], "additionalProperties": false }, "y": { "type": "object", "properties": { "label": { "type": "string" }, "unit": { "type": "string" }, "format": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "currency": { "type": "string" }, "decimals": { "type": "number" }, "higher_is_better": { "type": "boolean" } }, "additionalProperties": false }, "x_measure": { "type": "object", "properties": { "label": { "type": "string" }, "unit": { "type": "string" }, "format": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "currency": { "type": "string" }, "decimals": { "type": "number" }, "higher_is_better": { "type": "boolean" } }, "additionalProperties": false }, "series": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string", "enum": [ "positive", "neutral", "negative", "other" ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "string", "number" ] }, "y": { "type": "number" }, "r": { "type": "number" }, "label": { "type": "string" }, "sources": { "description": "Indexes in `sources`: where this value was published.", "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "x", "y" ], "additionalProperties": false } } }, "required": [ "name", "points" ], "additionalProperties": false } }, "events": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "end": { "type": "string" }, "label": { "type": "string" }, "detail": { "type": "string" }, "sources": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "date", "label" ], "additionalProperties": false } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "object", "properties": { "label": { "type": "string" }, "unit": { "type": "string" }, "format": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "currency": { "type": "string" }, "decimals": { "type": "number" }, "higher_is_better": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "key", "label" ], "additionalProperties": false } }, "rows": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number", "null" ] } } }, "kpis": { "description": "The key figures above the chart: latest, change, high.", "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "number" }, "format": { "type": "object", "properties": { "label": { "type": "string" }, "unit": { "type": "string" }, "format": { "type": "string", "enum": [ "number", "percent", "currency" ] }, "currency": { "type": "string" }, "decimals": { "type": "number" }, "higher_is_better": { "type": "boolean" } }, "additionalProperties": false }, "change": { "type": "object", "properties": { "value": { "type": "number" }, "percent": { "type": "boolean" } }, "required": [ "value", "percent" ], "additionalProperties": false } }, "required": [ "label", "value" ], "additionalProperties": false } }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "string", "number" ] }, "y": { "type": "number" }, "series": { "type": "string" }, "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "peak", "max", "min", "last", "event" ] } }, "required": [ "x", "text", "kind" ], "additionalProperties": false } }, "highlight": { "type": "string" }, "total": { "type": "number" }, "part_of_whole": { "type": "boolean" }, "scale": { "type": "string", "enum": [ "linear", "log" ] }, "smoothing": { "description": "Moving average drawn over the raw series, in points.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attribution": { "type": "string" } }, "required": [ "type", "title", "x", "y", "series" ], "additionalProperties": false }, { "type": "null" } ], "description": "What is drawn: series, key figures, annotations, sources. Null with plan_only." }, "compatible_types": { "type": "array", "items": { "type": "string", "enum": [ "line", "area", "bar", "bar_horizontal", "stacked_bar", "pie", "donut", "scatter", "funnel", "timeline", "kpi", "table" ] }, "description": "The chart types this data supports." }, "plan": { "anyOf": [ { "type": "object", "properties": { "recipe": { "type": "string", "enum": [ "coverage", "coverage_compare", "share_of_voice", "tone", "tone_compare", "outlets", "timeline", "figure_trend", "figure_compare", "answers", "index_prices", "index_scatter", "index_availability", "index_brands", "data", "series", "people", "outlet", "stories" ], "description": "What was measured: coverage, share_of_voice, tone, outlets, timeline, figure_trend, figure_compare, answers, or index_* from your custom index." }, "intent": { "type": "string" }, "measure": { "type": "string" }, "x_axis": { "type": "string" }, "type": { "type": "string", "enum": [ "line", "area", "bar", "bar_horizontal", "stacked_bar", "pie", "donut", "scatter", "funnel", "timeline", "kpi", "table" ] }, "part_of_whole": { "type": "boolean" }, "confidence": { "type": "number" }, "alternatives": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "line", "area", "bar", "bar_horizontal", "stacked_bar", "pie", "donut", "scatter", "funnel", "timeline", "kpi", "table" ] }, "probability": { "type": "number" } }, "required": [ "type", "probability" ], "additionalProperties": false }, "description": "Other chart types that fit: switch with PATCH, free." }, "topic": { "type": "string" }, "entities": { "type": "array", "items": { "type": "string" } }, "needs": { "type": "object", "properties": { "queries": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "ultra", "fast", "normal", "deep" ] }, "days": { "type": "number" }, "min_points": { "type": "number" }, "max_results": { "type": "number" } }, "required": [ "queries", "mode", "days", "min_points", "max_results" ], "additionalProperties": false, "description": "The data it needs before drawing." } }, "required": [ "recipe", "intent", "measure", "x_axis", "type", "part_of_whole", "confidence", "alternatives", "topic", "entities", "needs" ], "additionalProperties": false }, { "type": "null" } ], "description": "From a query: what was measured and why this chart. Null for your own data." }, "interpretation": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string", "description": "What we understood you expect to see: «Finishing positions of the last Formula 1 race»." }, "confidence": { "type": "number" }, "alternatives": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "probability": { "type": "number" } }, "required": [ "label", "probability" ], "additionalProperties": false }, "description": "Other readings of the query: pass one as `interpretation` to chart it instead." } }, "required": [ "label", "confidence", "alternatives" ], "additionalProperties": false }, { "type": "null" } ], "description": "From a query in words. Null for your own data, a custom index or a typed question." }, "rung": { "anyOf": [ { "type": "string", "enum": [ "exact", "partial", "related", "coverage", "stories" ] }, { "type": "null" } ], "description": "How close the chart is to what was asked. exact: the data itself, complete and verified; partial: a verified part (the podium); related: another view of the same question (the most mentioned names); coverage: the coverage or the timeline; stories: the top stories. Null for your own data." }, "improving": { "type": "boolean", "description": "Still looking for what was asked: the stored chart (embed, image) updates itself if it arrives. Poll GET /v1/charts/{id} or use stream: true." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "source", "published_at" ], "additionalProperties": false } }, "embed_url": { "description": "An iframe that adapts to its width, with tooltips. Add ?theme= to change the theme.", "type": [ "string", "null" ] }, "image_url": { "description": "PNG at twice the resolution, for chat, email or slides.", "type": [ "string", "null" ] }, "svg_url": { "type": [ "string", "null" ] }, "svg": { "description": "The SVG, with include_svg or store: false.", "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "cached": { "type": "boolean", "description": "The same request in the last 10 minutes: the same chart, not billed." }, "usage": { "type": "object", "properties": { "cost_usd": { "type": "number" }, "mode": { "anyOf": [ { "type": "string", "enum": [ "ultra", "fast", "normal", "deep", "data" ] }, { "type": "null" } ] }, "queries": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "cost_usd", "mode", "queries", "duration_ms" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } } }, "required": [ "id", "object", "type", "theme", "locale", "chart", "compatible_types", "plan", "interpretation", "rung", "improving", "sources", "embed_url", "image_url", "svg_url", "svg", "created_at", "expires_at", "cached", "usage", "warnings" ], "additionalProperties": false }