Nytimes Semantic API
Browse all Nytimes APIs✓ Official Vendor SpecData EnrichmentData TransformationapiKey2 EndpointsREST
For Agents
Resolve people, organizations, descriptors, and other named entities against the NYT controlled vocabulary and return linked-data records.
Use for: Resolve a person's name to a NYT semantic concept, Find every NYT-tagged article about a specific organization, Get linked-data references for a NYT descriptor tag, Search the NYT vocabulary for a topic keyword
Not supported: Does not return full article text, free-text article search, or autocomplete suggestions — use for resolving named entities against the NYT controlled vocabulary only.
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.
Install Jentic One Beta
Connect the Semantic API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Semantic API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Semantic API.
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
Patterns agents use Semantic API for, with concrete tasks.
★ 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.
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.
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.
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.
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
2 endpoints — 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.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
The NYT api-key is stored encrypted in the Jentic vault and injected into the api-key query parameter at execution time. The same credential authenticates every NYT API in the workspace, so a single rotation refreshes Semantic, Geographic, TimesTags, and the others together.
Intent-based discovery
Agents search Jentic for 'resolve named entity to NYT concept' or 'look up NYT controlled vocabulary' and Jentic returns the matching /search.json or /name endpoint with parameter schema, removing the need to read the NYT semantic documentation.
Time to first call
Direct integration: half a day to read the NYT linked-data semantics, wire the api-key, and parse the concept-type taxonomy. Through Jentic: under 15 minutes.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Semantic API through Jentic.
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.
GET STARTED