canonical: https://jentic.com/apis/nytimes.com/semantic-api

# Nytimes Semantic API

The New York Times Semantic API exposes the NYT controlled vocabulary of people, places, organizations, descriptors, titles of works, and other named entities used to tag NYT articles. Two endpoints support the workflow: /search.json returns concepts matching a query string with optional concept-type filtering, and /name/{concept-type}/{specific-concept}.json returns the linked-data record for a single concept including article references, related concepts, and external resource links. The API is designed for entity linking, knowledge-graph enrichment, and disambiguating named entities mentioned in editorial content.

## For AI agents

Resolve people, organizations, descriptors, and other named entities against the NYT controlled vocabulary and return linked-data records.

## Scope

Does not return full article text, free-text article search, or autocomplete suggestions - use for resolving named entities against the NYT controlled vocabulary only.

## Capabilities

- Search the NYT controlled vocabulary by free-text query across all concept types
- Filter searches to a specific concept type such as nytd_per for people
- Retrieve the full linked-data record for a single named NYT concept
- Surface the article references attached to a concept for cross-content linking
- Pull related concepts grouped by their relationship type
- Page through large result sets via the offset parameter

## Use cases

### Entity Linking in News Pipelines

Resolve named entities extracted from text against the NYT controlled vocabulary so downstream systems use stable concept identifiers. The /search.json endpoint accepts a query and optional concept_type filter, returning candidate concepts ranked by relevance for a downstream picker.

Example prompt: Call /search.json?query=Apple&concept_type=nytd_org and return the candidate organization concepts with concept name and article count for downstream selection.

### Knowledge Graph Enrichment

Enrich an internal knowledge graph by attaching NYT concept identifiers to people, organization, and topic nodes. Each /name/{concept-type}/{specific-concept}.json call returns the full linked-data record with related concepts and article references, supporting batch enrichment runs.

Example prompt: Call /name/nytd_per/elon_musk.json and return the related-concepts list and article-references count for graph enrichment.

### Topic Coverage Browser

Build a topic browser that surfaces every NYT article tagged with a chosen descriptor. The semantic endpoint returns article references for the concept, which can be combined with the Article Search API for full content lookup, supporting topic-deep editorial exploration.

Example prompt: Call /name/nytd_des/climate_change.json and return the article-references list as a topic-deep coverage feed.

### Agent-Driven Entity Resolution via Jentic

An AI editorial assistant uses Jentic to resolve a name mentioned by a user against the NYT vocabulary at runtime. Jentic returns the matching /search.json operation, the agent loads the schema and executes the call without manually reading the NYT semantic linked-data documentation.

Example prompt: Search Jentic for 'resolve named entity to NYT concept', load the /search.json operation, and execute it with query='Federal Reserve' and concept_type='nytd_org'.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /search.json | Search the NYT controlled vocabulary by query string |
| GET | /name/{concept-type}/{specific-concept}.json | Get the linked-data record for a specific NYT concept |

## Key resources

- **Concept Search** — Free-text search over the NYT controlled vocabulary with optional concept-type filtering.
- **Named Concept Records** — Linked-data records for individual NYT concepts including article references and related concepts.

## Why Jentic

- **Setup:** Wiring the NYT Semantic API by hand means registering for an NYT developer key, appending it to the api-key query parameter on every call, and handling retries and rate limits yourself against api.nytimes.com. Through Jentic you install once, import the Semantic API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** This API only resolves named entities against the NYT controlled vocabulary through read GETs, so scope it by operation: limit the agent to the operations it needs, such as concept search and concept lookup by name, and leave the rest out. You choose which operations it may call, so nothing beyond vocabulary lookup 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 'resolve a named entity to an NYT concept' or 'look up the NYT controlled vocabulary', and Jentic returns the matching /search.json or /name operation with its input schema so the agent calls the right endpoint without reading the NYT semantic documentation.

## Related APIs

- **NYT Geographic API** — Geographic extension of the Semantic API specifically for places.
- **NYT TimesTags API** — Autocomplete-style tag matcher across the same NYT vocabulary.
- **NYT Top Stories API** — Returns NYT articles by section that can be cross-referenced against resolved concepts.

## FAQ

### What authentication does the NYT Semantic API use?

Authentication is an API key passed as the api-key query parameter on /search.json and /name/{concept-type}/{specific-concept}.json. 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 holds the raw key.

### Which concept types does the Semantic API support?

The vocabulary covers nytd_per (people), nytd_org (organizations), nytd_geo (geographies), nytd_des (descriptors and topics), and titles of works such as books, films, and plays. Pass the concept_type query parameter on /search.json or include it as a path segment on /name/{concept-type}/{specific-concept}.json.

### What are the rate limits for the NYT Semantic API?

NYT enforces 500 requests per day and 5 requests per minute per API key, shared across all NYT developer APIs. Cache concept identifiers because they are stable, and batch enrichment runs to stay well within the limit.

### How do I resolve a person's name to a NYT concept through Jentic?

Search Jentic for 'resolve named entity to NYT concept', load the /search.json operation, and execute it with query set to the name and concept_type set to nytd_per. The response returns ranked candidate person concepts.

### Is the NYT Semantic API free to use?

Yes. NYT offers the Semantic API at no cost on the developer portal for non-commercial use within published rate limits. Commercial or high-volume use requires direct contact with the NYT licensing team.

### Does the Semantic API return full article text for tagged articles?

No. It returns article references (URL and headline metadata) attached to each concept, not full text. To retrieve content, pass the article URL to the Article Search API or follow the URL to nytimes.com directly.

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

Yes. Because your Jentic One instance is self-hosted, you decide which operations the agent may call, and your own rules are enforced at execution time. This API only performs read-only lookups against the NYT controlled vocabulary, so you can scope the agent to just the operations it needs, such as concept search on /search.json and concept lookup by name on /name/{concept-type}/{specific-concept}.json, and leave the rest out. Nothing beyond the vocabulary lookups you grant will run.