REST API

News search API reference

JSON over HTTPS. Send your API key as Authorization: Bearer nw_… to https://nearwire.dev/api/v1. Every endpoint below is also in the OpenAPI spec and the interactive reference, where you can try requests.

Get an API key Try it in the browser

Search

Find related stories using an article’s existing embedding

POST /api/v1/articles/{articleId}/related

Excludes the original article. Supports time, source and similarity filters. Costs one search request; no new embedding is generated.

parameter	in	type	description
articleId *	path	string (uuid)
limit	body	integer	Default: 10.
minScore	body	number	Minimum cosine similarity
since	body	string	Only articles published on/after this time. Accepts an ISO 8601 timestamp or a humanized time such as "1h", "30m", "7d", "last 24h", "yesterday" or "oct 1" (calendar dates resolve in UTC).
until	body	string	Only articles published on/before this time. Accepts an ISO 8601 timestamp or a humanized time such as "1h", "30m", "7d", "last 24h", "yesterday" or "oct 1" (calendar dates resolve in UTC).
feedIds	body	string (uuid)[]

Semantic news search

POST /api/v1/search

Search news articles by meaning. Provide either a natural-language `query` (embedded server-side) or your own `embedding`.

parameter	in	type	description
requiredTerms	body	string[]	All case-insensitive literal substrings must occur in title or description
excludedPhrases	body	string[]	Reject articles containing any case-insensitive literal substring in title or description
mode	body	"semantic" \| "keyword" \| "hybrid"	Default: "semantic".
query	body	string	Natural-language search term
embedding	body	number[]	Precomputed 1536-dim embedding (text-embedding-3-small)
limit	body	integer	Default: 10.
minScore	body	number	Minimum cosine similarity
since	body	string	Only articles published on/after this time. Accepts an ISO 8601 timestamp or a humanized time such as "1h", "30m", "7d", "last 24h", "yesterday" or "oct 1" (calendar dates resolve in UTC).
until	body	string	Only articles published on/before this time. Accepts an ISO 8601 timestamp or a humanized time such as "1h", "30m", "7d", "last 24h", "yesterday" or "oct 1" (calendar dates resolve in UTC).
feedIds	body	string (uuid)[]

Feeds

List indexed news sources

GET /api/v1/feeds

Account

Current month's usage

GET /api/v1/usage

Monitoring

Saved-query matches; 30-day inbox, paginated

GET /api/v1/monitoring/inbox

parameter	in	type
queryId	query	string (uuid)
unreadOnly	query	"true" \| "false"
cursor	query	string (uuid)

Mark a match read or unread

PATCH /api/v1/monitoring/inbox/{id}

parameter	in	type	description
id *	path	string (uuid)
read *	body	boolean

Saved queries, endpoints and monitoring usage

GET /api/v1/monitoring

Create an endpoint; returns signing secret once

POST /api/v1/webhook-endpoints

parameter	in	type	description
name *	body	string
url *	body	string

Verify endpoint ownership

POST /api/v1/webhook-endpoints/{id}/verify

parameter	in	type	description
id *	path	string (uuid)

Rotate signing secret; requires verification again

POST /api/v1/webhook-endpoints/{id}/rotate

parameter	in	type	description
id *	path	string (uuid)

Delete endpoint and its queries/history

DELETE /api/v1/webhook-endpoints/{id}

parameter	in	type	description
id *	path	string (uuid)

Monitor newly indexed matching articles

POST /api/v1/saved-queries

parameter	in	type	description
requiredTerms	body	string[]	All case-insensitive literal substrings must occur in title or description
excludedPhrases	body	string[]	Reject articles containing any case-insensitive literal substring in title or description
name *	body	string
query *	body	string
endpointId	body	string (uuid) \| null	Default: null.
minScore	body	number	Default: 0.35.
feedIds	body	string (uuid)[]
intervalMinutes	body	object	Default: 1.

Replace query; starts a new forward-only version

PUT /api/v1/saved-queries/{id}

parameter	in	type	description
id *	path	string (uuid)
requiredTerms	body	string[]	All case-insensitive literal substrings must occur in title or description
excludedPhrases	body	string[]	Reject articles containing any case-insensitive literal substring in title or description
name *	body	string
query *	body	string
endpointId	body	string (uuid) \| null	Default: null.
minScore	body	number	Default: 0.35.
feedIds	body	string (uuid)[]
intervalMinutes	body	object	Default: 1.

Pause or resume query

PATCH /api/v1/saved-queries/{id}

parameter	in	type	description
id *	path	string (uuid)
active *	body	boolean

Delete query and its delivery history

DELETE /api/v1/saved-queries/{id}

parameter	in	type	description
id *	path	string (uuid)

Last 50 events; paginate with cursor

GET /api/v1/webhook-events

parameter	in	type	description
cursor	query	string (uuid)

Immutable payload and attempt history

GET /api/v1/webhook-events/{id}

parameter	in	type	description
id *	path	string (uuid)

Replay the same event ID and payload

POST /api/v1/webhook-events/{id}/replay

parameter	in	type	description
id *	path	string (uuid)

* required. Rate limits and quotas are on the pricing page. For AI agents, see the MCP server guide.