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

# Nytimes TimesTags API

The New York Times TimesTags API is an autocomplete service over the NYT controlled vocabulary used to tag NYT articles. A single /timestags endpoint accepts a partial query string and returns ranked tag suggestions across persons, organizations, locations, descriptors, titles of works, and other entity types. Each suggestion includes the canonical tag string with a leading classifier (e.g. 'Per:', 'Org:', 'Geo:'), letting an autocomplete UI label suggestions by entity type. The API is the recommended front door for type-ahead lookups before deeper linked-data calls into the Semantic and Geographic APIs.

## For AI agents

Get autocomplete-style tag suggestions from the NYT controlled vocabulary as a user types a partial query.

## Scope

Does not return article references, full linked-data records, or coordinates for places - use for autocomplete suggestions over the NYT controlled vocabulary only.

## Capabilities

- Suggest NYT vocabulary tags from a partial query string
- Filter suggestions by entity type filter such as Per, Org, or Geo
- Limit the number of returned suggestions via the max query parameter
- Surface the canonical capitalised tag string for each match
- Power type-ahead UIs for editorial content management systems
- Pre-resolve entities before deeper Semantic API or Geographic API calls

## Use cases

### Editorial Tagging Type-Ahead

Power a type-ahead picker in a CMS so journalists tag NYT-controlled-vocabulary entities consistently. The /timestags endpoint accepts a query parameter with the partial string and an optional filter for entity type, returning ranked tag suggestions in canonical capitalisation. Each response is fast enough for keystroke-by-keystroke UI updates.

Example prompt: Call /timestags?query=Apple&max=10 and return the top 10 tag suggestions with their entity-type prefix for picker UI rendering.

### Pre-Resolution Before Semantic Lookup

Use TimesTags to narrow a user's free-text query to the canonical NYT vocabulary form before issuing a Semantic API call for the full linked-data record. The autocomplete output gives the agent a confident tag string, which it then passes to /name/{concept-type}/{specific-concept}.json on the Semantic API to retrieve article references and related concepts.

Example prompt: Call /timestags?query=federal+reserve&filter=(Org) and return the highest-ranked Org suggestion for downstream /name lookup on the Semantic API.

### Faceted Search Filter Builder

Build a faceted search filter over NYT-tagged content where users select tags from autocomplete suggestions rather than free-text queries. The TimesTags API supplies the filter values; the Article Search API consumes them as fq facets.

Example prompt: Call /timestags?query=climate&filter=(Des) and return the descriptor suggestions to populate the search facet dropdown.

### Agent-Driven Tag Suggestion via Jentic

An AI editorial assistant uses Jentic to call TimesTags whenever a user mentions an entity by partial name. Jentic returns the /timestags operation, the agent loads the schema and executes the call without manually wiring the api-key or learning the filter syntax for entity types.

Example prompt: Search Jentic for 'autocomplete NYT vocabulary tag', load the /timestags operation, and execute it with query='gates' and filter='(Per)'.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /timestags | Get autocomplete tag suggestions matching a partial query |

## Key resources

- **Tag Suggestions** — Autocomplete-ranked tag matches across the NYT controlled vocabulary, filterable by entity type.

## Why Jentic

- **Setup:** Wiring the NYT TimesTags API by hand means registering for an NYT developer key, adding it to the api-key query parameter, and building your own retry and rate-limit handling against api.nytimes.com. Through Jentic you install once, import the TimesTags API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** TimesTags exposes a single read-only autocomplete operation over the NYT controlled vocabulary, so scope it by operation: limit the agent to the tag-suggestion 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 'autocomplete an NYT vocabulary tag' or 'suggest NYT tags', and Jentic returns the /timestags operation with its filter syntax in the input schema so the agent calls it without reading the NYT documentation.

## Related APIs

- **NYT Semantic API** — Linked-data follow-up to TimesTags suggestions, returning article references and related concepts.
- **NYT Geographic API** — Geographic-specific extension for the Geo tag suggestions returned by TimesTags.
- **NYT Top Stories API** — Section-level NYT articles that can be filtered downstream by resolved tag.

## FAQ

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

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

### How do I filter suggestions to only people or only locations?

Pass the filter query parameter with a parenthesised type code such as (Per) for persons, (Org) for organizations, (Geo) for locations, or (Des) for descriptors. Combine multiple types with a comma, e.g. filter=(Per,Org). The default returns matches across every type.

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

NYT enforces 500 requests per day and 5 requests per minute per API key, shared across all NYT developer APIs. For type-ahead UIs, debounce keystrokes by 250 ms and only call after 2-3 characters to stay under the per-minute cap.

### How do I get tag suggestions for a partial name through Jentic?

Search Jentic for 'autocomplete NYT vocabulary tag', load the /timestags operation, and execute it with query set to the partial string and an optional filter type. Jentic returns the parameter schema so the agent uses the correct filter syntax.

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

Yes. NYT offers TimesTags 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 this API return article references or only the tag string?

TimesTags returns only the canonical tag string with its entity-type prefix. To retrieve article references, related concepts, and full linked-data records, pass the resolved tag to the Semantic API's /name endpoint or to the Geographic API for locations.

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

Yes. Jentic One is self-hosted, so you run your own instance and your own rules decide which operations and credentials the agent may use. The TimesTags API exposes a single read-only autocomplete operation over the NYT controlled vocabulary, so you scope it by operation: grant your agent only the tag-suggestion call on /timestags and nothing else. No other behaviour runs unless you add it, and your NYT api-key stays under your control rather than in the agent's context.