Vital · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Junction Aggregate API

4 actions 4 updates phrasing extends openapi/vital-io-aggregate-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Vital's API. It is a proposal applied on top of the contract, not a document Vital publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 4

$.info

$.paths['/aggregate/v1/user/{user_id}/query'].post

$.paths['/aggregate/v1/user/{user_id}/continuous_query/{query_id_or_slug}/result_table'].get

$.paths['/aggregate/v1/user/{user_id}/continuous_query/{query_id_or_slug}/task_history'].get

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Junction Aggregate API
  version: 1.0.0
extends: openapi/vital-io-aggregate-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 3
- target: $.paths['/aggregate/v1/user/{user_id}/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an aggregate query over a user's data
      effect: read
      questions:
      - Can I run a custom aggregation over one user's health data for a set timeframe?
      - What kinds of queries can I bundle into a single aggregate request for a user?
      instructions:
      - text: Run aggregate queries {queries} for user {user} over timeframe {timeframe}.
        slots:
          queries: requestBody.queries
          user: path.user_id
          timeframe: requestBody.timeframe
      - text: Aggregate {user}'s data across {timeframe} with the queries I describe.
        slots:
          user: path.user_id
          timeframe: requestBody.timeframe
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aggregate/v1/user/{user_id}/continuous_query/{query_id_or_slug}/result_table'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a continuous query's result table
      effect: read
      questions:
      - Where can I read the latest output table of a continuous query set up for a user?
      - Is the output of a continuous aggregate query available as a table?
      instructions:
      - text: Fetch the result table for continuous query {query} on user {user}.
        slots:
          query: path.query_id_or_slug
          user: path.user_id
      - text: Show what continuous query {query} has produced for {user} so far.
        slots:
          query: path.query_id_or_slug
          user: path.user_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/aggregate/v1/user/{user_id}/continuous_query/{query_id_or_slug}/task_history'].get
  update:
    x-apievangelist-phrasing:
      intent: List a continuous query's past runs
      effect: read
      questions:
      - Can I see when a user's continuous query last ran and whether it succeeded?
      - Which past executions exist for a continuous query, and can I page through them?
      instructions:
      - text: List the task history for continuous query {query} on user {user}.
        slots:
          query: path.query_id_or_slug
          user: path.user_id
      - text: Show the last {limit} runs of continuous query {query} for {user}, starting at cursor {cursor}.
        slots:
          limit: query.limit
          query: path.query_id_or_slug
          user: path.user_id
          cursor: query.next_cursor
      method: generated
      generated: '2026-10-01'