canonical: https://jentic.com/apis/nytimes.com/top-stories-api

# Nytimes Top Stories

The New York Times Top Stories API returns the editor-curated lineup of articles from any NYT section front. A single GET endpoint accepts a section name (such as home, world, business, technology, opinion, or arts) and returns the ranked article list with title, byline, abstract, kicker, web URL, geographic and organisational facets, and embedded multimedia at multiple sizes. The API mirrors the NYTimes.com section fronts and is ideal for surfacing curated section-level coverage rather than chronological wire feeds.

## For AI agents

Get the editor-curated NYT articles from any section front, including home, world, business, technology, opinion, and arts.

## Scope

Does not provide full article body text, chronological publication ordering, or engagement metrics - use for editor-curated NYT section-front lineups only.

## Capabilities

- Retrieve the curated article lineup for any NYT section front
- Pull the NYT homepage lineup via the home section value
- Filter to vertical-specific section fronts such as Technology or Opinion
- Surface multiple-sized image media for each article
- Pull geographic, person, and organisational facets attached to each article
- Use the editor-curated ordering rather than publish-time ordering

## Use cases

### NYT Section Front Mirror

Mirror the NYT homepage or any vertical section front in a third-party app. The /{section}.{format} endpoint returns the editor-curated article ordering with title, byline, abstract, kicker, multimedia, and the canonical URL. A typical implementation calls the home section every 5 minutes and renders the response as a card grid.

Example prompt: Call /home.json and render the first 12 articles as a homepage card grid with title, kicker, abstract, and the largest media URL.

### Vertical-Focused Reader Feed

Power a reader app that focuses on a single NYT vertical (e.g. Technology, Arts, Opinion). The Top Stories API returns the editor-curated section front with the same hierarchy NYT readers see on NYTimes.com, so the app preserves editorial priority rather than reverse-chronological order.

Example prompt: Call /technology.json and return the top 10 articles with byline, abstract, and the medium-sized media URL.

### Editorial Briefing Generator

Generate a daily editorial briefing summarising the NYT-curated top stories across multiple sections. An agent calls the Top Stories endpoint for each chosen section, extracts titles and abstracts, and feeds them into a summarisation prompt for a morning briefing email or Slack post.

Example prompt: Loop sections ['home','politics','business','technology'] calling /{section}.json for each, then summarise the top 3 articles per section.

### Agent-Driven Top Stories Lookup via Jentic

An AI news assistant uses Jentic to fetch the NYT-curated top stories on demand when a user asks 'what's on the NYT homepage?'. Jentic returns the /{section}.{format} operation, the agent loads the schema and executes the call without manually wiring the section path.

Example prompt: Search Jentic for 'get NYT top stories', load the /{section}.{format} operation, and execute it with section='home' and format='json'.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /{section}.{format} | Get the curated top stories for a NYT section front |

## Key resources

- **Section Top Stories** — Editor-curated article lineup for any NYT section front.

## Why Jentic

- **Setup:** Wiring the NYT Top Stories API by hand means registering for an NYT developer key, adding it to the api-key query parameter, and handling retries and rate limits yourself against api.nytimes.com. Through Jentic you install once, import the Top Stories API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Top Stories exposes a single read-only section-front lookup, so scope it by operation: limit the agent to the section-lineup call it needs and nothing else. You choose which operations it may call, so no other behaviour runs unless you add it.
- **Credential handling:** Your NYT api-key is stored once, encrypted, by your own Jentic One instance and injected into the api-key query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get the NYT top stories' or 'fetch a NYT section front', and Jentic returns the /{section}.{format} operation with its input schema so the agent calls the right path without reading the NYT documentation.

## Related APIs

- **NYT Times Newswire API** — Reverse-chronological wire feed rather than the editor-curated section front.
- **NYT Most Popular API** — Reader-engagement-ranked lists rather than editor-curated section fronts.
- **NYT Community API** — Reader comments on the same article URLs surfaced by Top Stories.

## FAQ

### What authentication does the NYT Top Stories API use?

Authentication is an API key passed as the api-key query parameter on /{section}.{format}. Provision a key at developer.nytimes.com. Through Jentic the credential lives in the vault and is injected at execution time, so the agent never sees the raw key.

### Which NYT sections does the API support?

The section path segment accepts arts, automobiles, books, business, fashion, food, health, home, insider, magazine, movies, nyregion, obituaries, opinion, politics, realestate, science, sports, sundayreview, technology, theater, t-magazine, travel, upshot, us, and world.

### What are the rate limits for the NYT Top Stories API?

NYT enforces 500 requests per day and 5 requests per minute per API key, shared across all NYT developer APIs. The section fronts change every few minutes at most, so cache responses for 2-5 minutes to comfortably stay within budget.

### How do I get the NYT homepage articles through Jentic?

Search Jentic for 'get NYT top stories', load the /{section}.{format} operation, and execute it with section='home' and format='json'. The response returns the editor-curated homepage lineup with multimedia and canonical URLs.

### Is the NYT Top Stories API free to use?

Yes. NYT offers Top Stories at no cost on the developer portal for non-commercial use within the published rate limits. Commercial redistribution of the curated lineup requires a separate licensing agreement with the NYT licensing team.

### How does Top Stories differ from the Times Newswire API?

Top Stories returns the editor-curated section front with hand-ordered articles. Times Newswire returns articles in reverse chronological publication order across all sources including AP. Use Top Stories to mirror NYT's editorial priorities and Times Newswire for chronological publish-stream monitoring.

### Can I limit what my agent is allowed to do with the NYT Top Stories API?

Yes. The NYT Top Stories API exposes a single read-only lookup, the /{section}.{format} section-front call, so with your self-hosted Jentic One instance you decide whether your agent may reach even that one operation. Because you set the rules on your own instance, the agent runs only the section-lineup call you approve and nothing else, and your NYT api-key stays under your control rather than the agent's. No other behaviour runs unless you add it.