API reference

Generated from the live OpenAPI specification (NaijaPress API v1.0.0). Base URL https://api.naijapress.com.

Try it

Paste one of your own API keys to send a request from this page. The key stays in this browser tab's memory and is sent only to the NaijaPress API. Requests count toward your quota.

Endpoint

API key

limit(query)

cursor(query)

q(query)

sort(query)

category(query)

subcategory(query)

topic(query)

entity(query)

location(query)

location_role(query)

source(query)

language(query)

geographic_scope(query)

published_after(query)

published_before(query)

GET https://api.naijapress.com/v1/news

News

GET/v1/newsList news

Newest-first list of enriched articles within your plan's access window (calendar days, Nigeria time). Cursor pagination; page size is capped at your plan's articles-per-call maximum.

Parameter	In	Type	Description
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)
q	query	string (optional)	Optional free-text filter; 3 characters minimum, up to your plan's maximum search query length (≤ 300 chars)
sort	query	"published_desc" \| "published_asc"	(default "published_desc")
category	query	string (optional)	Category slug, e.g. `economy` (≤ 40 chars)
subcategory	query	string (optional)	(≤ 80 chars)
topic	query	string (optional)	Topic id or slug (≤ 200 chars)
entity	query	string (optional)	Entity id or slug (≤ 200 chars)
location	query	string (optional)	Location id or slug (includes child places) (≤ 200 chars)
location_role	query	"mentioned" \| "event" (optional)	Restrict location matches to a role (advanced)
source	query	string (optional)	Source id or slug (≤ 120 chars)
language	query	string (optional)	(≤ 10 chars)
geographic_scope	query	"local" \| "state" \| "national" \| "regional" \| "global" (optional)	Advanced filter
published_after	query	string · date-time (optional)	ISO 8601; inclusive
published_before	query	string · date-time (optional)	ISO 8601; inclusive

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Article_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text

GET/v1/news/{slug}Get an article

Fetch one article by slug or id. Articles outside your plan's access window return 404.

Parameter	In	Type	Description
slug*	path	string

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ItemResponse_Article_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text

GET/v1/news/{slug}/relatedRelated news

Articles related through the same event cluster or shared canonical entities/topics (±14 days).

Parameter	In	Type	Description
slug*	path	string
limit	query	integer	(min 1, max 50, default 10)

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_ScoredArticle_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text
score	number (optional)	Ranking score; see docs for how it is computed for each endpoint
match	object (optional)	Ranking diagnostics (e.g. keyword and semantic ranks for hybrid search)

Search

GET/v1/searchKeyword search

Full-text keyword search (supports quotes, `or` and `-exclusion`). Works without embeddings.

Parameter	In	Type	Description
q*	query	string	Free-text query. Trimmed; 3 characters minimum, up to your plan's maximum search query length (≤ 300 chars)
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)
category	query	string (optional)	Category slug, e.g. `economy` (≤ 40 chars)
subcategory	query	string (optional)	(≤ 80 chars)
topic	query	string (optional)	Topic id or slug (≤ 200 chars)
entity	query	string (optional)	Entity id or slug (≤ 200 chars)
location	query	string (optional)	Location id or slug (includes child places) (≤ 200 chars)
location_role	query	"mentioned" \| "event" (optional)	Restrict location matches to a role (advanced)
source	query	string (optional)	Source id or slug (≤ 120 chars)
language	query	string (optional)	(≤ 10 chars)
geographic_scope	query	"local" \| "state" \| "national" \| "regional" \| "global" (optional)	Advanced filter
published_after	query	string · date-time (optional)	ISO 8601; inclusive
published_before	query	string · date-time (optional)	ISO 8601; inclusive

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_ScoredArticle_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text
score	number (optional)	Ranking score; see docs for how it is computed for each endpoint
match	object (optional)	Ranking diagnostics (e.g. keyword and semantic ranks for hybrid search)

GET/v1/search/semanticSemantic search

Meaning-based search over article embeddings. `score` is cosine similarity in [−1, 1].

Parameter	In	Type	Description
q*	query	string	Free-text query. Trimmed; 3 characters minimum, up to your plan's maximum search query length (≤ 300 chars)
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)
min_similarity	query	number (optional)	(min -1, max 1)
category	query	string (optional)	Category slug, e.g. `economy` (≤ 40 chars)
subcategory	query	string (optional)	(≤ 80 chars)
topic	query	string (optional)	Topic id or slug (≤ 200 chars)
entity	query	string (optional)	Entity id or slug (≤ 200 chars)
location	query	string (optional)	Location id or slug (includes child places) (≤ 200 chars)
location_role	query	"mentioned" \| "event" (optional)	Restrict location matches to a role (advanced)
source	query	string (optional)	Source id or slug (≤ 120 chars)
language	query	string (optional)	(≤ 10 chars)
geographic_scope	query	"local" \| "state" \| "national" \| "regional" \| "global" (optional)	Advanced filter
published_after	query	string · date-time (optional)	ISO 8601; inclusive
published_before	query	string · date-time (optional)	ISO 8601; inclusive

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_ScoredArticle_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text
score	number (optional)	Ranking score; see docs for how it is computed for each endpoint
match	object (optional)	Ranking diagnostics (e.g. keyword and semantic ranks for hybrid search)

GET/v1/search/hybridHybrid search

Keyword + semantic retrieval fused with Reciprocal Rank Fusion (k=60). `score` = Σ 1/(60 + rank) over the two rankings; `match` shows each component rank.

Parameter	In	Type	Description
q*	query	string	Free-text query. Trimmed; 3 characters minimum, up to your plan's maximum search query length (≤ 300 chars)
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)
category	query	string (optional)	Category slug, e.g. `economy` (≤ 40 chars)
subcategory	query	string (optional)	(≤ 80 chars)
topic	query	string (optional)	Topic id or slug (≤ 200 chars)
entity	query	string (optional)	Entity id or slug (≤ 200 chars)
location	query	string (optional)	Location id or slug (includes child places) (≤ 200 chars)
location_role	query	"mentioned" \| "event" (optional)	Restrict location matches to a role (advanced)
source	query	string (optional)	Source id or slug (≤ 120 chars)
language	query	string (optional)	(≤ 10 chars)
geographic_scope	query	"local" \| "state" \| "national" \| "regional" \| "global" (optional)	Advanced filter
published_after	query	string · date-time (optional)	ISO 8601; inclusive
published_before	query	string · date-time (optional)	ISO 8601; inclusive

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_ScoredArticle_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text
score	number (optional)	Ranking score; see docs for how it is computed for each endpoint
match	object (optional)	Ranking diagnostics (e.g. keyword and semantic ranks for hybrid search)

Taxonomy

GET/v1/categoriesList categories

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Category_

slug	string
name	string
description	string
subcategories	SubcategoryRef[] (optional)

GET/v1/categories/{slug}Get a category

Parameter	In	Type	Description
slug*	path	string

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ItemResponse_Category_

slug	string
name	string
description	string
subcategories	SubcategoryRef[] (optional)

GET/v1/categories/{slug}/subcategoriesList a category's subcategories

Parameter	In	Type	Description
slug*	path	string

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Subcategory_

slug	string
name	string
description	string
category	CategoryRef

GET/v1/subcategories/{slug}Get a subcategory

Parameter	In	Type	Description
slug*	path	string

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ItemResponse_Subcategory_

slug	string
name	string
description	string
category	CategoryRef

Entities

GET/v1/entitiesList or search entities

Parameter	In	Type	Description
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)
q	query	string (optional)	Name or alias prefix (≤ 200 chars)
type	query	string (optional)	(≤ 40 chars)

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Entity_

id	string
slug	string
name	string
type	string
description	string (optional)
aliases	string[]
article_count	integer

GET/v1/entities/{entity_id}Get an entity

Parameter	In	Type	Description
entity_id*	path	string

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ItemResponse_Entity_

id	string
slug	string
name	string
type	string
description	string (optional)
aliases	string[]
article_count	integer

GET/v1/entities/{entity_id}/newsNews mentioning an entity

Parameter	In	Type	Description
entity_id*	path	string
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Article_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text

Topics

GET/v1/topicsList or search topics

Parameter	In	Type	Description
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)
q	query	string (optional)	(≤ 200 chars)

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Topic_

id	string
slug	string
label	string
description	string (optional)
aliases	string[]
parent	TopicRef (optional)
article_count	integer

GET/v1/topics/{topic_id}Get a topic

Parameter	In	Type	Description
topic_id*	path	string

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ItemResponse_Topic_

id	string
slug	string
label	string
description	string (optional)
aliases	string[]
parent	TopicRef (optional)
article_count	integer

GET/v1/topics/{topic_id}/newsNews about a topic

Parameter	In	Type	Description
topic_id*	path	string
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Article_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text

Locations

GET/v1/locationsList or search locations

Parameter	In	Type	Description
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 50)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)
q	query	string (optional)	(≤ 200 chars)
type	query	"country" \| "region" \| "state" \| "lga" \| "city" \| "other" (optional)
parent	query	string (optional)	Parent location id or slug (≤ 200 chars)

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Location_

id	string
slug	string
name	string
type	string
country_code	string (optional)
parent	PlaceRef (optional)
aliases	string[]
article_count	integer

GET/v1/locations/{location_id}Get a location

Parameter	In	Type	Description
location_id*	path	string

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ItemResponse_Location_

id	string
slug	string
name	string
type	string
country_code	string (optional)
parent	PlaceRef (optional)
aliases	string[]
article_count	integer

GET/v1/locations/{location_id}/newsNews about a location

Parameter	In	Type	Description
location_id*	path	string
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 20)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)
role	query	"mentioned" \| "event" (optional)	Advanced: restrict to event location or mentions

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Article_

id	string
slug	string
title	string
source	SourceRef
published_at	string · date-time
ingested_at	string · date-time
language	string (optional)
author	string (optional)
image_url	string (optional)
summary	string (optional)	AI-generated summary of the publisher's reporting (Growth and Enterprise plans)
category	CategoryRef (optional)
subcategory	SubcategoryRef (optional)
entities	EntityRef[] (optional)
topics	TopicRef[] (optional)
geography	Geography (optional)
sentiment	Sentiment (optional)
event_cluster_id	string (optional)
content	string (optional)	Full text; only for licensed sources on plans that include it
attribution	string	Required attribution text

Sources

GET/v1/sourcesList sources

Parameter	In	Type	Description
limit	query	integer	Articles per call; values above your plan's maximum are capped to it (min 1, max 100, default 50)
cursor	query	string (optional)	Cursor from a previous response (≤ 500 chars)

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ListResponse_Source_

id	string
slug	string
name	string
website	string (optional)
language	string
country	string
description	string (optional)
article_count	integer

GET/v1/sources/{source_id}Get a source

Parameter	In	Type	Description
source_id*	path	string

Responses

200 — Successful Response
401 — Missing, invalid or revoked API key
403 — Not included in your plan
404 — Not Found
422 — Invalid parameters
429 — Rate limit or monthly quota exceeded

Response schema: ItemResponse_Source_

id	string
slug	string
name	string
website	string (optional)
language	string
country	string
description	string (optional)
article_count	integer

Health

GET/health/liveLiveness probe

Responses

200 — Successful Response

GET/health/readyReadiness probe

Reports only up/down per dependency; no internal details.

Responses

200 — Successful Response