{"openapi": "3.1.0", "info": {"title": "Dounia News licensed API", "version": "1", "description": "Titles, short summaries, categories and stories of Burkinabe media. Never full articles, never a publisher's address. Every article has `url`: an absolute link through Dounia News that you must use when sending a reader to the article. Show the attribution `Source: Dounia News`. Send `Authorization: Bearer dnk_...`. Daily quota depends on your plan: see the `X-Quota-*` headers; over quota answers 429."}, "servers": [{"url": "https://news.dounia.net/partners/v1"}], "paths": {"/trending": {"get": {"summary": "The most read articles of the last days (7 by default), by counted visits.", "parameters": [{"name": "lang", "in": "query", "required": false, "description": "Content language (see /meta/ content_languages). Default fr; unknown means fr.", "schema": {"type": "string"}}, {"name": "days", "in": "query", "required": false, "description": "1 to 30, default 7.", "schema": {"type": "integer"}}], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"language": {"type": "string"}, "days": {"type": "integer"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}}, "required": ["language", "days", "results"]}}}}}}}, "/shared": {"get": {"summary": "The most shared articles of the last days (7 by default), with `share_count`.", "parameters": [{"name": "lang", "in": "query", "required": false, "description": "Content language (see /meta/ content_languages). Default fr; unknown means fr.", "schema": {"type": "string"}}, {"name": "days", "in": "query", "required": false, "description": "1 to 30, default 7.", "schema": {"type": "integer"}}], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"language": {"type": "string"}, "days": {"type": "integer"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}}, "required": ["language", "days", "results"]}}}}}}}, "/articles": {"get": {"summary": "Articles, ranked (top sources get a head start), or filtered.", "parameters": [{"name": "lang", "in": "query", "required": false, "description": "Content language (see /meta/ content_languages). Default fr; unknown means fr.", "schema": {"type": "string"}}, {"name": "q", "in": "query", "required": false, "description": "Every word must appear in title or summary, accents and case ignored. Articles with the words in the title come first. At most 6 words, 100 characters.", "schema": {"type": "string"}}, {"name": "category", "in": "query", "required": false, "description": "Category slug.", "schema": {"type": "string"}}, {"name": "tag", "in": "query", "required": false, "description": "Tag slug.", "schema": {"type": "string"}}, {"name": "source", "in": "query", "required": false, "description": "Source slug.", "schema": {"type": "string"}}, {"name": "story", "in": "query", "required": false, "description": "Story id.", "schema": {"type": "integer"}}, {"name": "page", "in": "query", "required": false, "description": "", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "required": false, "description": "", "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ArticlePage"}}}}}}}, "/articles/{id}": {"get": {"summary": "One article and up to 10 others of its story.", "parameters": [{"name": "id", "in": "path", "required": true, "description": "", "schema": {"type": "integer"}}, {"name": "lang", "in": "query", "required": false, "description": "Content language (see /meta/ content_languages). Default fr; unknown means fr.", "schema": {"type": "string"}}], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ArticleDetail"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/stories": {"get": {"summary": "Stories told by at least two articles, newest first.", "parameters": [{"name": "lang", "in": "query", "required": false, "description": "Content language (see /meta/ content_languages). Default fr; unknown means fr.", "schema": {"type": "string"}}, {"name": "page", "in": "query", "required": false, "description": "", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "required": false, "description": "", "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoryPage"}}}}}}}, "/stories/{id}": {"get": {"summary": "A story, its articles and up to 4 related stories.", "parameters": [{"name": "id", "in": "path", "required": true, "description": "", "schema": {"type": "integer"}}, {"name": "lang", "in": "query", "required": false, "description": "Content language (see /meta/ content_languages). Default fr; unknown means fr.", "schema": {"type": "string"}}], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoryDetail"}}}}, "404": {"description": "Not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/categories": {"get": {"summary": "Categories that have articles, most used first.", "parameters": [{"name": "lang", "in": "query", "required": false, "description": "Content language (see /meta/ content_languages). Default fr; unknown means fr.", "schema": {"type": "string"}}], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"language": {"type": "string"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/LabelWithCount"}}}, "required": ["language", "results"]}}}}}}}, "/tags": {"get": {"summary": "Most used tags.", "parameters": [{"name": "lang", "in": "query", "required": false, "description": "Content language (see /meta/ content_languages). Default fr; unknown means fr.", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "required": false, "description": "", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 30}}], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"language": {"type": "string"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/LabelWithCount"}}}, "required": ["language", "results"]}}}}}}}, "/sources": {"get": {"summary": "Sources that have articles.", "parameters": [], "security": [{"bearer": []}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/SourceWithCount"}}}, "required": ["results"]}}}}}}}}, "components": {"schemas": {"Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}, "required": ["code", "message"]}}, "required": ["error"]}, "Source": {"type": "object", "properties": {"slug": {"type": "string"}, "name": {"type": "string"}, "short_name": {"type": "string", "description": "A short form of the name for tight places (\"AIB\"); the full name when there is none."}, "logo_url": {"type": "string", "description": "The outlet's logo; empty when it has none."}}, "required": ["slug", "name", "short_name", "logo_url"]}, "SourceWithCount": {"allOf": [{"$ref": "#/components/schemas/Source"}, {"type": "object", "properties": {"homepage_url": {"type": "string", "description": "The outlet's own home page (the one address of theirs the API gives: link the logo and name to it)."}, "article_count": {"type": "integer"}}, "required": ["homepage_url", "article_count"]}]}, "Label": {"type": "object", "properties": {"slug": {"type": "string"}, "name": {"type": "string"}, "language": {"type": "string"}}, "required": ["slug", "name", "language"]}, "LabelWithCount": {"type": "object", "properties": {"slug": {"type": "string"}, "name": {"type": "string"}, "language": {"type": "string"}, "article_count": {"type": "integer"}}, "required": ["slug", "name", "language", "article_count"]}, "StoryBrief": {"type": "object", "properties": {"id": {"type": "integer"}, "slug": {"type": "string", "description": "From the French title: the same in every language."}, "title": {"type": "string"}, "language": {"type": "string"}, "fell_back": {"type": "boolean"}, "article_count": {"type": "integer"}, "source_count": {"type": "integer"}}, "required": ["id", "slug", "title", "language", "fell_back", "article_count", "source_count"]}, "Article": {"type": "object", "properties": {"id": {"type": "integer"}, "title": {"type": "string"}, "summary": {"type": "string"}, "language": {"type": "string", "description": "Language of title and summary: the one asked for, or fr."}, "fell_back": {"type": "boolean", "description": "True when the text is French because there is no translation: show a badge, never hide the article."}, "source": {"$ref": "#/components/schemas/Source"}, "published_at": {"type": "string", "format": "date-time"}, "date_estimated": {"type": "boolean"}, "cover_image_url": {"type": "string", "description": "May be empty."}, "categories": {"type": "array", "items": {"$ref": "#/components/schemas/Label"}}, "tags": {"type": "array", "items": {"$ref": "#/components/schemas/Label"}}, "story": {"oneOf": [{"$ref": "#/components/schemas/StoryBrief"}, {"type": "null"}]}, "breaking": {"type": "boolean", "description": "An editor flagged it as breaking news (show a 'Derni\u00e8re minute' badge)."}, "go_path": {"type": "string", "description": "Our redirect link, relative to the site: open `{site_url}{go_path}?l=<lang>&c=app` in the browser. It records the visit and sends the reader to the publisher. There is never a publisher address in the API."}}, "required": ["id", "title", "summary", "language", "fell_back", "source", "published_at", "date_estimated", "cover_image_url", "categories", "tags", "story", "breaking", "go_path"]}, "ArticleDetail": {"allOf": [{"$ref": "#/components/schemas/Article"}, {"type": "object", "properties": {"story_articles": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}}, "required": ["story_articles"]}]}, "Story": {"allOf": [{"$ref": "#/components/schemas/StoryBrief"}, {"type": "object", "properties": {"first_published_at": {"oneOf": [{"type": "string", "format": "date-time"}, {"type": "null"}]}, "last_published_at": {"oneOf": [{"type": "string", "format": "date-time"}, {"type": "null"}]}, "sources": {"type": "array", "items": {"$ref": "#/components/schemas/Source"}}, "lead": {"oneOf": [{"$ref": "#/components/schemas/Article"}, {"type": "null"}]}}, "required": ["first_published_at", "last_published_at", "sources", "lead"]}]}, "StoryDetail": {"allOf": [{"$ref": "#/components/schemas/Story"}, {"type": "object", "properties": {"articles": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}, "related": {"type": "array", "items": {"$ref": "#/components/schemas/Story"}}}, "required": ["articles", "related"]}]}, "Page": {"type": "object", "properties": {"count": {"type": "integer"}, "page": {"type": "integer"}, "pages": {"type": "integer"}, "page_size": {"type": "integer"}, "language": {"type": "string"}}, "required": ["count", "page", "pages", "page_size", "language"]}, "ArticlePage": {"allOf": [{"$ref": "#/components/schemas/Page"}, {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}}, "required": ["results"]}]}, "StoryPage": {"allOf": [{"$ref": "#/components/schemas/Page"}, {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/Story"}}}, "required": ["results"]}]}, "Home": {"type": "object", "properties": {"language": {"type": "string"}, "stories": {"type": "array", "items": {"$ref": "#/components/schemas/Story"}}, "articles": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}, "breaking": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}, "pinned": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}}, "required": ["language", "stories", "articles", "breaking", "pinned"]}, "BillingPlans": {"type": "object", "properties": {"language": {"type": "string"}, "providers": {"type": "array", "items": {"type": "string"}}, "results": {"type": "array", "items": {"type": "object"}}}, "required": ["language", "providers", "results"]}, "MyBilling": {"type": "object", "properties": {"entitlements": {"type": "array", "items": {"type": "string"}}, "ends_at": {"type": ["string", "null"]}, "trial_available": {"type": "boolean"}, "payments": {"type": "array", "items": {"type": "object"}}}, "required": ["entitlements", "ends_at", "trial_available", "payments"]}, "Alert": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "terms": {"type": "string"}, "language": {"type": "string"}, "frequency": {"type": "string"}, "effective_frequency": {"type": "string"}, "active": {"type": "boolean"}, "sources": {"type": "array", "items": {"type": "string"}}, "categories": {"type": "array", "items": {"type": "string"}}, "matches_total": {"type": "integer"}, "matches_7d": {"type": "integer"}, "recent": {"type": "array", "items": {"$ref": "#/components/schemas/Article"}}}, "required": ["id", "name", "terms", "language", "frequency", "effective_frequency", "active", "sources", "categories", "matches_total", "matches_7d", "recent"]}, "Alerts": {"type": "object", "properties": {"limits": {"type": "object", "properties": {"max": {"type": "integer"}, "instant": {"type": "boolean"}, "used": {"type": "integer"}}, "required": ["max", "instant", "used"]}, "monitors": {"type": "array", "items": {"$ref": "#/components/schemas/Alert"}}}, "required": ["limits", "monitors"]}, "ListingCard": {"type": "object", "properties": {"id": {"type": "string"}, "kind": {"type": "string"}, "title": {"type": "string"}, "organisation": {"type": "object", "properties": {"name": {"type": "string"}, "verified": {"type": "boolean"}}, "required": ["name", "verified"]}, "city": {"type": "string"}, "country": {"type": "string"}, "attrs": {"type": "object"}, "language": {"type": "string"}, "featured": {"type": "boolean"}, "preview": {"type": "string"}, "published_at": {"oneOf": [{"type": "string"}, {"type": "null"}]}, "expires_at": {"oneOf": [{"type": "string"}, {"type": "null"}]}}, "required": ["id", "kind", "title", "organisation", "city", "country", "attrs", "language", "featured", "preview", "published_at", "expires_at"]}, "ListingPage": {"allOf": [{"$ref": "#/components/schemas/Page"}, {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/ListingCard"}}}, "required": ["results"]}]}, "ListingDetail": {"allOf": [{"$ref": "#/components/schemas/ListingCard"}, {"type": "object", "properties": {"description": {"type": "string"}, "closes_on": {"oneOf": [{"type": "string"}, {"type": "null"}]}, "apply": {"type": "object", "properties": {"email": {"type": "string"}, "whatsapp": {"type": "string"}, "url": {"type": "string"}}, "required": ["email", "whatsapp", "url"]}}, "required": ["description", "apply"]}]}, "Employer": {"type": "object", "properties": {"organisation": {"oneOf": [{"type": "object"}, {"type": "null"}]}, "listings": {"type": "array", "items": {"$ref": "#/components/schemas/ListingDetail"}}, "limits": {"type": "object", "properties": {"max_open": {"type": "integer"}, "open": {"type": "integer"}, "days": {"type": "integer"}}, "required": ["max_open", "open", "days"]}}, "required": ["organisation", "listings", "limits"]}, "Developer": {"type": "object", "properties": {"client": {"type": ["object", "null"]}}, "required": ["client"]}, "Trends": {"type": "object", "properties": {"language": {"type": "string"}, "days": {"type": "integer"}, "period": {"type": "object", "properties": {"from": {"type": "string"}, "to": {"type": "string"}}, "required": ["from", "to"]}, "min_visits": {"type": "integer"}, "definitions_version": {"type": "integer"}, "rising": {"type": "array", "items": {"type": "object"}}, "topics": {"type": "array", "items": {"type": "object"}}, "tags": {"type": "array", "items": {"type": "object"}}, "stories": {"type": "array", "items": {"type": "object"}}, "sources": {"type": "array", "items": {"type": "object"}}, "daily": {"type": "array", "items": {"type": "object", "properties": {"date": {"type": "string"}, "visits": {"type": "integer"}}, "required": ["date", "visits"]}}}, "required": ["language", "days", "period", "min_visits", "definitions_version", "rising", "topics", "tags", "stories", "sources", "daily"]}, "Digest": {"type": "object", "properties": {"state": {"type": "string"}, "frequency": {"type": "string"}, "language": {"type": "string"}}, "required": ["state", "frequency", "language"]}, "Language": {"type": "object", "properties": {"code": {"type": "string"}, "name": {"type": "string"}, "native_name": {"type": "string"}, "rtl": {"type": "boolean"}}, "required": ["code", "name", "native_name", "rtl"]}, "Meta": {"type": "object", "properties": {"api_version": {"type": "integer"}, "site_url": {"type": "string"}, "contact_url": {"type": "string"}, "app": {"type": "object", "properties": {"min_version": {"type": "string"}, "latest_version": {"type": "string"}}, "required": ["min_version", "latest_version"]}, "ads_enabled": {"type": "boolean"}, "features": {"type": "object", "additionalProperties": {"type": "string"}}, "default_language": {"type": "string"}, "ui_languages": {"type": "array", "items": {"$ref": "#/components/schemas/Language"}}, "content_languages": {"type": "array", "items": {"$ref": "#/components/schemas/Language"}}}, "required": ["api_version", "site_url", "contact_url", "app", "ads_enabled", "features", "default_language", "ui_languages", "content_languages"]}, "Sitemap": {"type": "object", "properties": {"stories": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "integer"}, "slug": {"type": "string"}, "last_published_at": {"oneOf": [{"type": "string"}, {"type": "null"}]}}, "required": ["id", "slug", "last_published_at"]}}, "categories": {"type": "array", "items": {"type": "string"}}, "sources": {"type": "array", "items": {"type": "string"}}}, "required": ["stories", "categories", "sources"]}, "User": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "first_name": {"type": "string"}, "last_name": {"type": "string"}, "email": {"type": "string"}, "preferred_language": {"type": "string", "description": "Language code the reader chose (\"fr\", \"en\"); empty = default."}}, "required": ["id", "name", "first_name", "last_name", "email", "preferred_language"]}, "SignedIn": {"type": "object", "properties": {"token": {"type": "string"}, "user": {"$ref": "#/components/schemas/User"}}, "required": ["token", "user"]}}, "securitySchemes": {"bearer": {"type": "http", "scheme": "bearer", "description": "Your key, dnk_..."}}}}