apiVersion: naftiko.io/v1
kind: Capability
metadata:
  name: nyt-article-search
  provider: new-york-times-company
  api: article-search-api
  tags:
    - News
    - Search
    - Articles
spec:
  summary: Search The New York Times article archive by keyword.
  description: |
    Wraps the NYT Article Search API (GET /svc/search/v2/articlesearch.json).
    Supports free-text queries, Lucene-style filter queries (fq=), date-range
    filters (begin_date, end_date), facet aggregation, sorting (newest, oldest,
    relevance), and pagination over up to 1,000 results (100 pages of 10).
  inputs:
    - name: query
      type: string
      required: true
      description: Free-text keyword query (q=).
    - name: filterQuery
      type: string
      required: false
      description: Lucene-style filter query passed as fq=.
    - name: beginDate
      type: string
      required: false
      description: Earliest publication date (YYYYMMDD).
    - name: endDate
      type: string
      required: false
      description: Latest publication date (YYYYMMDD).
    - name: sort
      type: string
      required: false
      enum: [newest, oldest, relevance]
    - name: page
      type: integer
      required: false
      minimum: 0
      maximum: 100
  outputs:
    - name: hits
      type: integer
    - name: articles
      type: array
      itemsRef: openapi/article-search-v2-openapi.yml#/definitions/Article
  operation:
    method: GET
    path: /articlesearch.json
    baseURL: https://api.nytimes.com/svc/search/v2
  auth:
    type: apiKey
    in: query
    name: api-key