{ "openapi": "3.1.0", "info": { "title": "Media Frame data API", "version": "1.0.0", "summary": "Tracks how policy ideas move from research institutions (think tanks) into the official record and enforcement, and how each source frames them over time.", "description": "Premium plan. Everything on the Media Frame board as JSON, refreshed every pipeline run: derived metrics, headlines, source links and redline fragments — never full article text. Create a key at https://mediaframe.me/auth/account. See /llms.txt for what is measured and its reliability." }, "servers": [ { "url": "https://mediaframe.me" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "paths": { "/v1/datasets": { "get": { "operationId": "listDatasets", "summary": "Datasets and the latest run's as_of.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Dataset index." }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/snapshot": { "get": { "operationId": "getSnapshot", "summary": "Every dataset in one document (usually a 302 to a gzip object).", "description": "Counts as 100 requests against the 2,000/day budget, and at most 20 snapshots per account per day. Prefer the per-dataset paths for frequent polling.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Snapshot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "302": { "description": "Presigned URL (5 min) to the gzip JSON." }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/series/framing_share": { "get": { "operationId": "seriesFramingShare", "summary": "BETA. Frame shares of a theme/source over a window, each with low/high bounds (95% sampling + gold-set per-frame precision/recall).", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." }, { "name": "edition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "EU", "UK", "US", "AU", "IN", "SG", "BR" ] }, "description": "Only pieces whose source is based in this region (#201). EU = EU institutions plus publishers based in a member state; each piece carries its source's `region`." }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Theme key (e.g. china). Give theme and/or source." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Named source as listed (e.g. EUISS)." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Days (share/series: back from the latest run; drift: per window)." } ], "responses": { "200": { "description": "BETA. Frame shares of a theme/source over a window, each with low/high bounds (95% sampling + gold-set per-frame precision/recall)." }, "400": { "description": "Missing theme/source or a bad parameter." }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/series/framing_drift": { "get": { "operationId": "seriesFramingDrift", "summary": "BETA. Each frame's share in the last window vs the one before, with the delta's 95% interval and a significance flag.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." }, { "name": "edition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "EU", "UK", "US", "AU", "IN", "SG", "BR" ] }, "description": "Only pieces whose source is based in this region (#201). EU = EU institutions plus publishers based in a member state; each piece carries its source's `region`." }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Theme key (e.g. china). Give theme and/or source." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Named source as listed (e.g. EUISS)." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Days (share/series: back from the latest run; drift: per window)." } ], "responses": { "200": { "description": "BETA. Each frame's share in the last window vs the one before, with the delta's 95% interval and a significance flag." }, "400": { "description": "Missing theme/source or a bad parameter." }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/series/theme_series": { "get": { "operationId": "seriesThemeSeries", "summary": "BETA. Dated frame-share series (per week or day) with bounds.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." }, { "name": "edition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "EU", "UK", "US", "AU", "IN", "SG", "BR" ] }, "description": "Only pieces whose source is based in this region (#201). EU = EU institutions plus publishers based in a member state; each piece carries its source's `region`." }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Theme key (e.g. china). Give theme and/or source." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Named source as listed (e.g. EUISS)." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Days (share/series: back from the latest run; drift: per window)." }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "week", "day" ] } }, { "name": "frame", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "BETA. Dated frame-share series (per week or day) with bounds." }, "400": { "description": "Missing theme/source or a bad parameter." }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/trajectories": { "get": { "operationId": "getTrajectories", "summary": "Policy arcs per theme: origin think tank -> official record -> action -> public.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Policy arcs per theme: origin think tank -> official record -> action -> public.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/signals": { "get": { "operationId": "getSignals", "summary": "The notable digest, incidents, upcoming deadlines and cross-jurisdiction diffusion.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "The notable digest, incidents, upcoming deadlines and cross-jurisdiction diffusion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/people": { "get": { "operationId": "getPeople", "summary": "People in the corpus: pieces, organizations, stages, revolving-door transitions.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "People in the corpus: pieces, organizations, stages, revolving-door transitions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/actors": { "get": { "operationId": "getActors", "summary": "The actor network: entities and their co-occurrence edges, each edge with the documents (headline, source, date, stage, link) that name both actors.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "The actor network: entities and their co-occurrence edges, each edge with the documents (headline, source, date, stage, link) that name both actors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/framing": { "get": { "operationId": "getFraming", "summary": "Frame distribution and shift per theme, plus the dated framing history.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Frame distribution and shift per theme, plus the dated framing history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/pieces": { "get": { "operationId": "getPieces", "summary": "Every analysed piece: source, headline, URL, date, themes and frame vector.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." }, { "name": "edition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "EU", "UK", "US", "AU", "IN", "SG", "BR" ] }, "description": "Only pieces whose source is based in this region (#201). EU = EU institutions plus publishers based in a member state; each piece carries its source's `region`." } ], "responses": { "200": { "description": "Every analysed piece: source, headline, URL, date, themes and frame vector.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/flow": { "get": { "operationId": "getFlow", "summary": "Frame contests: the same story framed differently across named sources.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Frame contests: the same story framed differently across named sources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/propagation": { "get": { "operationId": "getPropagation", "summary": "Who set a frame and which official body adopted or reframed it, with lag.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Who set a frame and which official body adopted or reframed it, with lag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/framers": { "get": { "operationId": "getFramers", "summary": "Each named source's lens, its drift, persuasion fingerprint and coverage concentration.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Each named source's lens, its drift, persuasion fingerprint and coverage concentration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/rhetoric": { "get": { "operationId": "getRhetoric", "summary": "Rhetorical strategy, frame demands, cast of the frame, delivery, and stances.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Rhetorical strategy, frame demands, cast of the frame, delivery, and stances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/coverage": { "get": { "operationId": "getCoverage", "summary": "Source health: per-source run history, status and fallback reasons.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Source health: per-source run history, status and fallback reasons.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/editorial": { "get": { "operationId": "getEditorial", "summary": "Document editorial trajectories: observed edits with redline fragments.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Document editorial trajectories: observed edits with redline fragments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/pulse": { "get": { "operationId": "getPulse", "summary": "GDELT coverage velocity per actor: spike ratio, day series, escalation, narrative gap, threat score, the outlets that drove the latest day (tone vs the pack) and risk-framing headline flags.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "GDELT coverage velocity per actor: spike ratio, day series, escalation, narrative gap, threat score, the outlets that drove the latest day (tone vs the pack) and risk-framing headline flags.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } }, "/v1/outlet_framing": { "get": { "operationId": "getOutletFraming", "summary": "Headline frame mix per news outlet within topic slices (e.g. the White House, Israel-Gaza) vs the peer median, with n, a Wilson CI and GDELT tone before/after a dated event.", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "br" ], "default": "en" }, "description": "Which board: en (mediaframe.me) or br (br.mediaframe.me)." } ], "responses": { "200": { "description": "Headline frame mix per news outlet within topic slices (e.g. the White House, Israel-Gaza) vs the peer median, with n, a Wilson CI and GDELT tone before/after a dated event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset": { "type": "string" }, "version": { "type": "string" }, "locale": { "type": "string", "enum": [ "en", "br" ] }, "as_of": { "type": "string" }, "run_id": { "type": "string" }, "description": { "type": "string" }, "data": {} } } } } }, "401": { "description": "Missing, unknown or revoked key." }, "403": { "description": "The key's account is not on the Premium plan." }, "429": { "description": "Daily request limit reached (resets 00:00 UTC)." }, "503": { "description": "Not published yet; retry after the next run." } } } } }, "externalDocs": { "description": "Orientation for language models", "url": "https://mediaframe.me/llms.txt" } }