TopicSummaryRequest

Summarize a set of articles. Provide either a template or custom instructions.

  • anonymous_id
    Type: string

    The anonymous visitor.

  • fl
    Type: array of string

    Fields to return for each source article.

  • force_refresh
    Type: boolean

    Regenerate and overwrite the cached summary instead of returning a cached result.

  • format
    Type: "markdown" or "html" or "json"enum

    Output format of the generated summary.

  • fq
    Type: string

    Selects the articles to summarize (Elasticsearch query-string syntax (Lucene)). Every matching catalog article — up to max_articles — is included in one summary.

    Examples:

    • "section:\"markets\"" — the markets section
    • "tags:\"interest rates\"" — a topic
    • "section:\"markets\" AND published_at:[NOW-7DAYS TO NOW]" — this week's articles (newsletter)
    • "rating:[4 TO *]" — numeric range
  • instructions
    Type: string

    Custom instructions for the summary (tone, length, structure…). Provide this or template.

  • max_articles
    Type: integer
    min:  
    1
    max:  
    200

    Maximum number of matching articles to include in the summary.

  • relevance_instruction
    Type: string | null

    Per-article relevance filter: each candidate is kept only if it satisfies this (strict LLM check). e.g. "Keep only if interest-rate policy is a primary subject, not a passing mention."

  • rules
    Type: array of string

    Rules the summary must satisfy; it is regenerated up to 3× to meet them. e.g. ["Must be under 200 words", "Each article must be cited"].

  • template
    Type: "newsletter_v1" or "newsvault"enum

    A built-in summary template. Provide this or instructions.

  • url_template
    Type: string

    Template applied to every link in the summary — use it to add click-tracking params, e.g. https://example.com{url}?utm_source=newsletter.

  • user_hash
    Type: string

    Hash of user_id/anonymous_id with your Secret API Key — send when calling from the browser with a Publishable key.

  • user_id
    Type: string

    The signed-in user. Use anonymous_id for visitors.

  • user_type
    Type: string

    User segment/type, used for rate limiting.

  • virtual_articles
    Type: array of object …10

    Extra articles not in your catalog to include. Prepended before catalog articles and cited identically.