Saved Searches

Persist a filter set and replay it later. The only write endpoints in the API.

Generated page

This page is generated from the published OpenAPI schema. Do not edit it by hand — run npm run generate:api.

GET /v1/saved-searches

Saved searches

Lists API-key owner scoped saved searches.

API key required

Example

curl -sS "https://theneuralledger.com/v1/saved-searches" \
  -H "Authorization: Bearer $TNL_API_KEY"

Responses

Status	Meaning
200	Successful response.
401	Missing or invalid API key.
429	Monthly API call limit exceeded.

POST /v1/saved-searches

Create saved search

Creates a saved search with filters and optional webhook alert settings.

API key required

Example

curl -sS "https://theneuralledger.com/v1/saved-searches" \
  -H "Authorization: Bearer $TNL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"What changed in copper markets this week?"}'

Responses

Status	Meaning
200	Successful response.
401	Missing or invalid API key.
429	Monthly API call limit exceeded.

GET /v1/saved-searches/{idOrSlug}

Saved search detail

Returns one saved search by id.

API key required

Path parameters

Name	Required	Description	Example
idOrSlug	yes	Story id, title slug, entity value, impact path value, ticker, or saved-search id depending on the endpoint.	—

Example

curl -sS "https://theneuralledger.com/v1/saved-searches/example-slug" \
  -H "Authorization: Bearer $TNL_API_KEY"

Responses

Status	Meaning
200	Successful response.
401	Missing or invalid API key.
429	Monthly API call limit exceeded.

PUT /v1/saved-searches/{idOrSlug}

Update saved search

Updates the saved query, filters, and alert settings.

API key required

Path parameters

Name	Required	Description	Example
idOrSlug	yes	Story id, title slug, entity value, impact path value, ticker, or saved-search id depending on the endpoint.	—

Example

curl -sS "https://theneuralledger.com/v1/saved-searches/example-slug" \
  -H "Authorization: Bearer $TNL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"What changed in copper markets this week?"}'

Responses

Status	Meaning
200	Successful response.
401	Missing or invalid API key.
429	Monthly API call limit exceeded.

DELETE /v1/saved-searches/{idOrSlug}

Delete saved search

Deletes a saved search.

API key required

Path parameters

Name	Required	Description	Example
idOrSlug	yes	Story id, title slug, entity value, impact path value, ticker, or saved-search id depending on the endpoint.	—

Example

curl -sS -X DELETE "https://theneuralledger.com/v1/saved-searches/example-slug" \
  -H "Authorization: Bearer $TNL_API_KEY"

Responses

Status	Meaning
200	Successful response.
401	Missing or invalid API key.
429	Monthly API call limit exceeded.

GET /v1/saved-searches/{idOrSlug}/results

Saved search results

Runs a saved search and returns the same paginated article envelope as /v1/news.

API key required

Path parameters

Name	Required	Description	Example
idOrSlug	yes	Story id, title slug, entity value, impact path value, ticker, or saved-search id depending on the endpoint.	—

Query parameters

Name	Required	Description	Example
page	no	Page number, starting at 1.	1
page_size	no	Stories per page. Alias: limit. Maximum 100.	50
cursor	no	Opaque cursor returned as page.next_cursor for the next page.	eyJvZmZzZXQiOjUwfQ
offset	no	Zero-based offset. Ignored when cursor is supplied.	100
fields	no	Comma-separated response fields to return. The id field is always included when present.	id,title,publishedAt,impactPaths
include	no	Comma-separated detail groups. Use full for all fields, or sources,claims,impactDetails,body for selected heavy fields.	sources,claims
sort	no	Feed order: pipeline for newest stories or popular for 12-hour freshness-bucketed popularity.	popular
country	no	G20 country filter from the story passive entities.	Japan
category	no	Normalized Neural Ledger story category.	Trading & Markets
entity	no	Passive entity text or id filter.	Federal Reserve
impact_path	no	Impact path text, id, or lookup token filter.	oil
tag	no	Normalized story tag filter.	tariff
q	no	Full-text query across titles, summaries, entities, tags, and impact paths.	tariff
published_since	no	Return stories published at or after this ISO date/time.	2026-05-01T00:00:00Z
published_until	no	Return stories published at or before this ISO date/time.	2026-05-31T23:59:59Z
updated_since	no	Return stories updated at or after this ISO date/time.	2026-05-01T00:00:00Z
updated_until	no	Return stories updated at or before this ISO date/time.	2026-05-31T23:59:59Z

Example

curl -sS "https://theneuralledger.com/v1/saved-searches/example-slug/results?page=1&page_size=50&cursor=eyJvZmZzZXQiOjUwfQ" \
  -H "Authorization: Bearer $TNL_API_KEY"

Responses

Status	Meaning
200	Successful response.
401	Missing or invalid API key.
429	Monthly API call limit exceeded.