# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Lytics Content API
  version: 1.0.0
extends: openapi/lytics-content-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 30
- target: $.paths['/api/content/topic'].get
  update:
    x-apievangelist-phrasing:
      intent: List topics in the content graph
      effect: read
      questions:
      - Which topics does my content graph contain?
      - Can I cap how many content topics come back?
      instructions:
      - text: List the topics in my content graph.
      - text: Show the first {limit} content topics.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topic/{topic}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a summary of one content topic
      effect: read
      questions:
      - Can I see a summary for a single content topic?
      - What does the content graph know about one specific topic?
      instructions:
      - text: Summarize content topic {topic}.
        slots:
          topic: path.topic
      - text: Show me the summary for topic {topic}.
        slots:
          topic: path.topic
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/rollup/{label}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a summary of a topic rollup by label
      effect: read
      questions:
      - Can I get a summary of a topic rollup using its label?
      - What does a labelled rollup of topics look like in aggregate?
      instructions:
      - text: Summarize the topic rollup labelled {label}.
        slots:
          label: path.label
      - text: Show the rollup summary for label {label}.
        slots:
          label: path.label
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topicrollup'].get
  update:
    x-apievangelist-phrasing:
      intent: List topic rollups
      effect: read
      questions:
      - Which topic rollups have been set up on my account?
      - Can I see all my topic rollups at once?
      instructions:
      - text: List all my topic rollups.
      - text: Show every topic rollup on the account.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topicblocklist'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the blocked topics list
      effect: read
      questions:
      - Which content topics are currently blocklisted?
      - Can I see the topics I've excluded from my content graph?
      instructions:
      - text: Show my topic blocklist.
      - text: List the topics I have blocked.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topicblocklist'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace the whole topic blocklist
      effect: write
      questions:
      - Can I overwrite my entire topic blocklist with a new set of topics?
      - Is there a way to replace every blocked topic in one call?
      instructions:
      - text: Replace my topic blocklist with a new list of topics.
      - text: Overwrite the full set of blocked topics.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topicblocklist'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or remove topics on the blocklist
      effect: write
      questions:
      - Can I add a few topics to my blocklist without replacing the rest?
      - How do I un-block a topic I blocked earlier?
      instructions:
      - text: Add these topics to my existing topic blocklist.
      - text: Un-block a topic by removing it from the blocklist.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topicrollup/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a topic rollup by id
      effect: read
      questions:
      - Can I fetch a single topic rollup by its id?
      - Which topics are inside a particular rollup?
      instructions:
      - text: Fetch topic rollup {id}.
        slots:
          id: path.id
      - text: Show the topics in rollup {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topicrollup/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a topic rollup
      effect: write
      questions:
      - Can I group several content topics into a named rollup?
      - What's needed to create a new topic rollup?
      instructions:
      - text: Create topic rollup {id}.
        slots:
          id: path.id
      - text: Set up a new rollup {id} grouping related topics.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topicrollup/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a topic rollup
      effect: destructive
      questions:
      - Can I delete a topic rollup I no longer need?
      - Does removing a rollup affect the topics inside it?
      instructions:
      - text: Delete topic rollup {id}.
        slots:
          id: path.id
      - text: Remove rollup {id} from my account.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/doc'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up content documents by URL or id
      effect: read
      questions:
      - Can I fetch stored content documents by their URLs?
      - What does the content table hold for a given document id?
      instructions:
      - text: Get the content documents for URLs {urls}.
        slots:
          urls: query.urls
      - text: Look up content documents with ids {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/doc/classify'].get
  update:
    x-apievangelist-phrasing:
      intent: Test-classify a document without saving it
      effect: read
      questions:
      - Can I see what topics a page would get without adding it to my corpus?
      - Is there a dry-run way to classify some text for debugging?
      instructions:
      - text: Classify {url} for debugging without adding it to the corpus.
        slots:
          url: query.url
      - text: 'Dry-run topic classification on this text: {text}.'
        slots:
          text: query.text
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/doc/classify'].post
  update:
    x-apievangelist-phrasing:
      intent: Classify a document and add it to the corpus
      effect: write
      questions:
      - Can I classify a URL and have it saved into my content corpus at the same time?
      - What topics get assigned when I classify and store a document?
      instructions:
      - text: Classify {url} and add it to the content corpus.
        slots:
          url: query.url
      - text: 'Classify this text and save it as a document: {text}.'
        slots:
          text: query.text
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/recommend/user/{fieldname}/{fieldval}'].get
  update:
    x-apievangelist-phrasing:
      intent: Recommend content for a user
      effect: read
      questions:
      - Can I get personalized content recommendations for one user?
      - Can recommendations skip content the user has already seen?
      - 'Which ranking options are there for recommendations: popular, recent or affinity?'
      instructions:
      - text: Recommend content from collection {contentsegment} for the user whose {fieldname} is {fieldval}.
        slots:
          contentsegment: query.contentsegment
          fieldname: path.fieldname
          fieldval: path.fieldval
      - text: Give the user with {fieldname} {fieldval} {limit} recommendations from {contentsegment} ranked by {rank}.
        slots:
          fieldname: path.fieldname
          fieldval: path.fieldval
          limit: query.limit
          contentsegment: query.contentsegment
          rank: query.rank
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/recommend/segment/{segId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Recommend content for an audience segment
      effect: read
      questions:
      - Can I get content recommendations for a whole audience segment rather than one user?
      - What content would best suit everyone in a segment?
      instructions:
      - text: Recommend content for segment {segId}.
        slots:
          segId: path.segId
      - text: Suggest {limit} pieces of content for audience segment {segId}.
        slots:
          limit: query.limit
          segId: path.segId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/recommend/{account}/user/{fieldname}/{fieldval}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get public content recommendations for a user
      effect: read
      questions:
      - Can I fetch content recommendations from the public endpoint that names the account in the path?
      - Is there a recommendation call I can use from a public page for a given account?
      instructions:
      - text: Get public recommendations from account {account} collection {contentsegment} for the user with {fieldname} {fieldval}.
        slots:
          account: path.account
          contentsegment: query.contentsegment
          fieldname: path.fieldname
          fieldval: path.fieldval
      - text: Using the public endpoint for account {account}, recommend {limit} items from {contentsegment} to {fieldname} {fieldval}.
        slots:
          account: path.account
          limit: query.limit
          contentsegment: query.contentsegment
          fieldname: path.fieldname
          fieldval: path.fieldval
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/taxonomy'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the topic taxonomy graph
      effect: read
      questions:
      - Can I see how my content topics relate to each other as a graph?
      - Is the topic taxonomy capped at a certain number of topics?
      instructions:
      - text: Show my content topic taxonomy.
      - text: 'Build the topic taxonomy graph with up to {limit} topics, split into cliques: {cliques}.'
        slots:
          limit: query.limit
          cliques: query.cliques
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/corpus'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a document to the content corpus
      effect: write
      questions:
      - Can I add a page to my content library so it can be recommended?
      - Can I add raw text with my own topics to the corpus?
      instructions:
      - text: Add {url} to my content corpus.
        slots:
          url: query.url
      - text: 'Add this text to the corpus tagged with topics {topics}: {text}.'
        slots:
          topics: query.topics
          text: query.text
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/filter/topic'].get
  update:
    x-apievangelist-phrasing:
      intent: Plot content topics for a segment
      effect: read
      questions:
      - Can I plot content topic data filtered to one segment?
      - What topic distribution shows up for a given audience?
      instructions:
      - text: Plot content topics for segment {segment_id}.
        slots:
          segment_id: query.segment_id
      - text: Show a topic plot with filters {filters}, limited to {limit} results.
        slots:
          filters: query.filters
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/doc/{docField}/{docId}/topic/{topicLabel}'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag a document with a topic
      effect: write
      questions:
      - Can I manually add a topic to a specific document?
      - Can I set how relevant a topic is when I attach it to content?
      instructions:
      - text: Add topic {topicLabel} to the document whose {docField} is {docId}.
        slots:
          topicLabel: path.topicLabel
          docField: path.docField
          docId: path.docId
      - text: Tag document {docField} {docId} with {topicLabel} at relevance {relevance}.
        slots:
          docField: path.docField
          docId: path.docId
          topicLabel: path.topicLabel
          relevance: query.relevance
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/doc/{docField}/{docId}/topic/{topicLabel}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a topic from a document
      effect: destructive
      questions:
      - Can I take a wrong topic off a document?
      - Is it possible to detach a topic from one piece of content?
      instructions:
      - text: Remove topic {topicLabel} from the document whose {docField} is {docId}.
        slots:
          topicLabel: path.topicLabel
          docField: path.docField
          docId: path.docId
      - text: Untag {topicLabel} from document {docField} {docId}.
        slots:
          topicLabel: path.topicLabel
          docField: path.docField
          docId: path.docId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/crawl'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a crawl of a website
      effect: write
      questions:
      - Can I kick off a crawl of my site to pull its content in?
      - Can one crawl cover several domains?
      instructions:
      - text: Start a content crawl of {domain}.
        slots:
          domain: query.domain
      - text: Crawl the domains {domains} for content.
        slots:
          domains: query.domains
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/metrics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get account content metrics
      effect: read
      questions:
      - What content metrics does my account have?
      - Can I see overall stats about my content library?
      instructions:
      - text: Show my account's content metrics.
      - text: Fetch the content stats for my account.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topic/cluster'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview the most central topic clusters
      effect: read
      questions:
      - Which topics are most central in my topic graph, and what clusters form around them?
      - Can I experiment with penalty and threshold to see different topic clusters?
      instructions:
      - text: Show the {limit} most central topics with their clusters.
        slots:
          limit: query.limit
      - text: Preview topic clusters using penalty {penalty} and threshold {threshold}.
        slots:
          penalty: query.penalty
          threshold: query.threshold
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topic/cluster'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a set of central topic clusters
      effect: write
      questions:
      - Can I save a collection of central topic clusters for my account?
      - Once I like the clustering settings, how do I create the clusters?
      instructions:
      - text: Create topic clusters from my {limit} most central topics.
        slots:
          limit: query.limit
      - text: Generate and save topic clusters with threshold {threshold}.
        slots:
          threshold: query.threshold
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/content/topic/cluster/{topicId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find topics related to one topic
      effect: read
      questions:
      - Which topics are related to a given topic, to help build a rollup?
      - Can I follow topic dependencies inward or outward from one topic?
      instructions:
      - text: Find topics related to {topicId}.
        slots:
          topicId: path.topicId
      - text: Show the cluster around topic {topicId} following direction {direction}.
        slots:
          topicId: path.topicId
          direction: query.direction
      method: generated
      generated: '2026-10-01'
- target: $.paths['/content/align'].post
  update:
    x-apievangelist-phrasing:
      intent: Score content alignment against topics
      effect: read
      questions:
      - How well does my content line up with a set of topics I care about?
      - Can I limit how many aligned documents come back when checking topic alignment?
      instructions:
      - text: Check how my content aligns with topics {topics}.
        slots:
          topics: requestBody.topics
      - text: Return the top {limit} documents aligned with topics {topics} using method {method}.
        slots:
          limit: query.limit
          topics: requestBody.topics
          method: query.method
      method: generated
      generated: '2026-10-02'
- target: $.paths['/content/classify'].post
  update:
    x-apievangelist-phrasing:
      intent: Classify a URL and show the steps taken
      effect: read
      questions:
      - What content gets extracted from a URL when it is classified, step by step?
      - Can I see each classification step the classifier ran on a page?
      instructions:
      - text: Run the classifier on {url} and show the extracted content and steps.
        slots:
          url: query.url
      - text: Explain how {url} was classified, step by step.
        slots:
          url: query.url
      method: generated
      generated: '2026-10-02'
- target: $.paths['/content/enrich'].post
  update:
    x-apievangelist-phrasing:
      intent: Enrich a URL or text with topics
      effect: read
      questions:
      - Can I get topics and inferred topics for a block of plain text?
      - What inferred topics would a URL be enriched with?
      instructions:
      - text: Enrich {url} with topics and inferred topics.
        slots:
          url: query.url
      - text: 'Find the topics and inferred topics in this text: {text}.'
        slots:
          text: query.text
      method: generated
      generated: '2026-10-02'
- target: $.paths['/content/opportunity'].get
  update:
    x-apievangelist-phrasing:
      intent: Get saved content opportunity metrics
      effect: read
      questions:
      - Where are my content opportunities according to the saved metrics?
      - Can I see the content opportunity snapshot from a past day?
      instructions:
      - text: Show my saved content opportunity metrics.
      - text: Get the content opportunity snapshot for {date}.
        slots:
          date: query.date
      method: generated
      generated: '2026-10-02'