> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Competitor

> One competitor's period score, trend, comparisons, prompts, engines and cited pages.

`page_url` also opens its rival-page pane, including daily-only discoveries.
With it, key can be the page's hostname instead of the competitor's brand key.
`with_details` adds weekly site changes and stored AI descriptions.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/competitors/{key}
openapi: 3.1.0
info:
  description: >-
    Access to one organization's brands, as the member who created the API key.
    A read-only key reads; a full-access key also starts, edits and runs that
    member's Snapshots on the organization's Snapshot credits. Each key may make
    120 requests a minute. Separate organization service tokens can start
    Snapshots and Full audits and read service audits. Every error is an RFC
    9457 problem (`application/problem+json`) whose `code` names it.
  summary: Read your brands' AI visibility and run Snapshots in Heralded.
  title: Heralded API
  version: '1'
servers:
  - url: https://api.heralded.ai
security: []
paths:
  /v1/brands/{brand_id}/competitors/{key}:
    get:
      tags:
        - v1
      summary: Get Competitor
      description: >-
        One competitor's period score, trend, comparisons, prompts, engines and
        cited pages.


        `page_url` also opens its rival-page pane, including daily-only
        discoveries.

        With it, key can be the page's hostname instead of the competitor's
        brand key.

        `with_details` adds weekly site changes and stored AI descriptions.
      operationId: getCompetitor
      parameters:
        - description: The brand's UUID from listBrands.
          in: path
          name: brand_id
          required: true
          schema:
            description: The brand's UUID from listBrands.
            format: uuid
            title: Brand Id
            type: string
        - description: A competitor key from list_competitors.
          in: path
          name: key
          required: true
          schema:
            description: A competitor key from list_competitors.
            maxLength: 300
            minLength: 1
            title: Key
            type: string
        - description: Check country or global. Omit for all.
          in: query
          name: country
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Check country or global. Omit for all.
            title: Country
        - description: Maximum rows (100).
          in: query
          name: limit
          required: false
          schema:
            default: 20
            description: Maximum rows (100).
            maximum: 100
            minimum: 1
            title: Limit
            type: integer
        - description: Prior next_cursor; keep filters and limit.
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                type: string
              - type: 'null'
            description: Prior next_cursor; keep filters and limit.
            title: Cursor
        - description: Completed scan id cutoff.
          in: query
          name: as_of
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Completed scan id cutoff.
            title: As Of
        - description: Rows to skip; prefer cursor paging.
          in: query
          name: offset
          required: false
          schema:
            default: 0
            description: Rows to skip; prefer cursor paging.
            minimum: 0
            title: Offset
            type: integer
        - description: >-
            Read AI answers (ai), Google shares without a score (search), or AI
            figures (all).
          in: query
          name: side
          required: false
          schema:
            default: all
            description: >-
              Read AI answers (ai), Google shares without a score (search), or
              AI figures (all).
            enum:
              - all
              - ai
              - search
            title: Side
            type: string
        - description: >-
            Country ISO code, europe for pooled Europe, or global for no
            country. Omit for all.
          in: query
          name: market
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Country ISO code, europe for pooled Europe, or global for no
              country. Omit for all.
            title: Market
        - description: >-
            Audience UUID, or all_buyers for topics for all buyers. Omit for
            all.
          in: query
          name: audience
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - const: all_buyers
                type: string
              - type: 'null'
            description: >-
              Audience UUID, or all_buyers for topics for all buyers. Omit for
              all.
            title: Audience
        - description: Answering AI engine.
          in: query
          name: engine
          required: false
          schema:
            anyOf:
              - enum:
                  - perplexity
                  - gemini
                  - openai
                  - google_aio
                  - ai_mode
                  - copilot
                  - claude
                type: string
              - type: 'null'
            description: Answering AI engine.
            title: Engine
        - description: Question type.
          in: query
          name: type
          required: false
          schema:
            anyOf:
              - enum:
                  - organic
                  - brand_specific
                  - competitor_comparison
                type: string
              - type: 'null'
            description: Question type.
            title: Type
        - description: Question intent.
          in: query
          name: intent
          required: false
          schema:
            anyOf:
              - enum:
                  - educational
                  - problem
                  - comparison
                  - transactional
                type: string
              - type: 'null'
            description: Question intent.
            title: Intent
        - description: Tracked topic UUID.
          in: query
          name: topic
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Tracked topic UUID.
            title: Topic
        - description: Question id from list_prompts.
          in: query
          name: prompt
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Question id from list_prompts.
            title: Prompt
        - description: Weekly-report period.
          in: query
          name: period
          required: false
          schema:
            default: 1w
            description: Weekly-report period.
            enum:
              - 1w
              - 4w
              - 12w
              - all
            title: Period
            type: string
        - description: Return bounded section previews.
          in: query
          name: preview
          required: false
          schema:
            default: false
            description: Return bounded section previews.
            title: Preview
            type: boolean
        - description: The section paged by limit and offset.
          in: query
          name: section
          required: false
          schema:
            anyOf:
              - enum:
                  - lost
                  - won
                  - pages
                  - questions
                  - work
                  - website
                  - changes
                type: string
              - type: 'null'
            description: The section paged by limit and offset.
            title: Section
        - description: Include weekly site changes and how AI describes this brand.
          in: query
          name: with_details
          required: false
          schema:
            default: false
            description: Include weekly site changes and how AI describes this brand.
            title: With Details
            type: boolean
        - description: Keep prompts or answers matching this brand-presence state.
          in: query
          name: you
          required: false
          schema:
            anyOf:
              - enum:
                  - named
                  - not_named
                type: string
              - type: 'null'
            description: Keep prompts or answers matching this brand-presence state.
            title: You
        - description: Select a topic by id, or untagged for prompts without a topic.
          in: query
          name: topic_id
          required: false
          schema:
            anyOf:
              - maxLength: 100
                type: string
              - type: 'null'
            description: Select a topic by id, or untagged for prompts without a topic.
            title: Topic Id
        - description: >-
            Also return this competitor-owned page's details, including
            daily-only discoveries.
          in: query
          name: page_url
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                minLength: 1
                type: string
              - type: 'null'
            description: >-
              Also return this competitor-owned page's details, including
              daily-only discoveries.
            title: Page Url
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1CompetitorDetail'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                code: invalid_cursor
                detail: The cursor is invalid or belongs to a different query.
                instance: example-request-id
                status: 400
                title: Bad Request
                type: https://docs.heralded.ai/errors-and-limits#invalid_cursor
              schema:
                $ref: '#/components/schemas/Problem'
          description: The cursor is invalid or belongs to a different query.
        '401':
          content:
            application/problem+json:
              example:
                code: invalid_token
                detail: >-
                  The Authorization header carries no API key Heralded knows: it
                  is missing, mistyped, revoked or expired.
                instance: example-request-id
                status: 401
                title: Unauthorized
                type: https://docs.heralded.ai/errors-and-limits#invalid_token
              schema:
                $ref: '#/components/schemas/Problem'
          description: No API key, or one that is unknown, revoked or expired.
          headers:
            WWW-Authenticate:
              schema:
                example: Bearer
                type: string
        '404':
          content:
            application/problem+json:
              example:
                code: not_found
                detail: Nothing here that this API key can read.
                instance: example-request-id
                status: 404
                title: Not Found
                type: https://docs.heralded.ai/errors-and-limits#not_found
              schema:
                $ref: '#/components/schemas/Problem'
          description: No such brand or answer, or the key's owner cannot read it.
        '409':
          content:
            application/problem+json:
              example:
                code: workspace_archived
                detail: The API key's organization is archived.
                instance: example-request-id
                status: 409
                title: Conflict
                type: https://docs.heralded.ai/errors-and-limits#workspace_archived
              schema:
                $ref: '#/components/schemas/Problem'
          description: The API key's organization is archived.
        '422':
          content:
            application/problem+json:
              example:
                code: invalid_request
                detail: The request's parameters are invalid; `errors` names each one.
                errors:
                  - loc:
                      - query
                      - limit
                    msg: Input should be less than or equal to 100
                    type: less_than_equal
                instance: example-request-id
                status: 422
                title: Unprocessable Content
                type: https://docs.heralded.ai/errors-and-limits#invalid_request
              schema:
                $ref: '#/components/schemas/ValidationProblem'
          description: A path or query parameter is invalid.
        '429':
          content:
            application/problem+json:
              example:
                code: rate_limited
                detail: >-
                  This caller is past its requests for the minute. Retry after
                  the seconds in Retry-After.
                instance: example-request-id
                rate_limit:
                  limit: 120
                  remaining: 0
                  reset: 60
                  window: 60
                status: 429
                title: Too Many Requests
                type: https://docs.heralded.ai/errors-and-limits#rate_limited
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
          description: The API key made more than 120 requests in the minute.
          headers:
            Retry-After:
              description: Seconds until the key may call again.
              schema:
                example: 60
                type: integer
      security:
        - apiKey: []
components:
  schemas:
    V1CompetitorDetail:
      properties:
        actions_total:
          default: 0
          description: All live work items about this subject before paging.
          title: Actions Total
          type: integer
        answers_link:
          anyOf:
            - $ref: '#/components/schemas/AnswersLink'
            - type: 'null'
        brand_key:
          title: Brand Key
          type: string
        capacity:
          $ref: '#/components/schemas/RosterPool'
        citation_evidence:
          default: complete
          enum:
            - complete
            - partial
            - unavailable
          title: Citation Evidence
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: The latest stored AI description.
          title: Description
        description_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the report supplying the AI description completed.
          title: Description At
        description_scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The report whose interpretation supplies the AI description.
          title: Description Scan Id
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        engines:
          items:
            $ref: '#/components/schemas/CompetitorEngine'
          title: Engines
          type: array
        figure_changes:
          additionalProperties:
            anyOf:
              - $ref: '#/components/schemas/FigureChange'
              - type: 'null'
          description: Each competitor figure’s comparison with the earlier period.
          title: Figure Changes
          type: object
        figure_trends:
          additionalProperties:
            items:
              $ref: '#/components/schemas/FigurePoint'
            type: array
          description: >-
            Weekly competitor figure values, including your score less theirs
            under gap.
          title: Figure Trends
          type: object
        figures:
          items:
            $ref: '#/components/schemas/Versus'
          title: Figures
          type: array
        focus_selection:
          anyOf:
            - $ref: '#/components/schemas/Focus'
            - type: 'null'
          description: The brand’s current focus selection and capacity.
        gap_delta:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Change in your score lead, yours less theirs; null when either
            comparison is unavailable or their baselines differ.
          title: Gap Delta
        history:
          items:
            $ref: '#/components/schemas/V1TrendPoint'
          title: History
          type: array
        is_tracked:
          title: Is Tracked
          type: boolean
        lost:
          $ref: '#/components/schemas/VersusPage'
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        most_said_against:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            With details, the negative opinion with the most holders in the
            period.
          title: Most Said Against
        most_said_for:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            With details, the positive opinion with the most holders in the
            period.
          title: Most Said For
        moves:
          anyOf:
            - $ref: '#/components/schemas/V1CompetitorSites'
            - type: 'null'
          description: The first page of stored changes on this competitor’s site.
        name:
          title: Name
          type: string
        next_step:
          anyOf:
            - $ref: '#/components/schemas/WorkRowResponse'
            - type: 'null'
          description: >-
            The highest-priority eligible work item across the subject’s entire
            live work selection, or null.
        pages:
          description: >-
            The most cited rival pages. A floor unless citation_evidence is
            complete.
          items:
            $ref: '#/components/schemas/CompetitorCitedPage'
          title: Pages
          type: array
        pages_total:
          description: >-
            The number of cited rival pages. A floor unless citation_evidence is
            complete.
          title: Pages Total
          type: integer
        paused_engines:
          description: >-
            The engines paused for the latest report in the period, respecting
            the engine filter.
          items:
            type: string
          title: Paused Engines
          type: array
        period:
          $ref: '#/components/schemas/V1Period'
        product_cards:
          anyOf:
            - $ref: '#/components/schemas/BrandProductCards'
            - type: 'null'
          description: >-
            Product-card figures for ecommerce brands; null for other brands and
            Google search.
        rival:
          anyOf:
            - $ref: '#/components/schemas/RivalPagePane'
            - type: 'null'
        score:
          $ref: '#/components/schemas/ScoreMark'
        tracked_since:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Tracked Since
        trend:
          $ref: '#/components/schemas/PromptTrend'
        unavailable_scans:
          default: 0
          title: Unavailable Scans
          type: integer
        versus:
          $ref: '#/components/schemas/Versus'
        website:
          anyOf:
            - $ref: '#/components/schemas/V1CompetitorSiteDetail'
            - type: 'null'
          description: Weekly site data and moves with with_details=true.
        won:
          $ref: '#/components/schemas/VersusPage'
        work:
          description: >-
            One page of live work explicitly about this subject, highest
            priority first.
          items:
            $ref: '#/components/schemas/WorkRowResponse'
          title: Work
          type: array
      required:
        - meta
        - product_cards
        - period
        - brand_key
        - name
        - domain
        - is_tracked
        - tracked_since
        - score
        - trend
        - history
        - versus
        - figures
        - lost
        - won
        - engines
        - paused_engines
        - pages
        - pages_total
        - citation_evidence
        - unavailable_scans
        - capacity
        - answers_link
        - rival
        - website
        - description
        - most_said_for
        - most_said_against
        - description_scan_id
        - description_at
        - work
        - actions_total
        - next_step
        - figure_trends
        - figure_changes
        - gap_delta
      title: V1CompetitorDetail
      type: object
    Problem:
      description: An RFC 9457 problem linking its code to human-readable documentation.
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        instance:
          default: ''
          title: Instance
          type: string
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
      title: Problem
      type: object
    ValidationProblem:
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ValidationIssue'
          title: Errors
          type: array
        instance:
          default: ''
          title: Instance
          type: string
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - errors
      title: ValidationProblem
      type: object
    RateLimitProblem:
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        instance:
          default: ''
          title: Instance
          type: string
        rate_limit:
          $ref: '#/components/schemas/RateLimitValues'
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - rate_limit
      title: RateLimitProblem
      type: object
    AnswersLink:
      properties:
        href:
          title: Href
          type: string
      required:
        - href
      title: AnswersLink
      type: object
    RosterPool:
      description: |-
        Roster size as a pool (MK-4). `cap` is `None` on a workspace with no
        active subscription to read one off.
      properties:
        cap:
          anyOf:
            - type: integer
            - type: 'null'
          title: Cap
        used:
          title: Used
          type: integer
      required:
        - used
        - cap
      title: RosterPool
      type: object
    CompetitorEngine:
      properties:
        change:
          anyOf:
            - $ref: '#/components/schemas/FigureChange'
            - type: 'null'
          description: The competitor's Heralded Score change on this engine.
        gap:
          anyOf:
            - type: integer
            - type: 'null'
          description: Your value minus the competitor's, or null if either is unmeasured.
          title: Gap
        key:
          description: The figure, prompt or engine key.
          title: Key
          type: string
        label:
          description: The display name of the figure, prompt or engine.
          title: Label
          type: string
        lead:
          anyOf:
            - enum:
                - you
                - them
                - level
              type: string
            - type: 'null'
          description: Which brand leads, or null if either is unmeasured.
          title: Lead
        them:
          anyOf:
            - type: integer
            - type: 'null'
          description: The competitor's value, or null when unmeasured.
          title: Them
        you:
          anyOf:
            - type: integer
            - type: 'null'
          description: Your brand's value, or null when unmeasured.
          title: You
      required:
        - key
        - label
        - them
        - you
        - gap
        - lead
        - change
      title: CompetitorEngine
      type: object
    FigureChange:
      properties:
        baseline:
          $ref: '#/components/schemas/ComparisonPeriod'
        cells_unpaired:
          title: Cells Unpaired
          type: integer
        compared_engines:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            The engines `delta` was sized on, when the baseline report asked
            other engines than the current period. The value and the trend still
            include every engine asked. Null when the size is the move the trend
            draws.
          title: Compared Engines
        delta:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            The move in points: the shown value minus the baseline's, both as
            the trend draws them, or both over `compared_engines` where it names
            engines. Null when the baseline has no value.
          title: Delta
        direction:
          enum:
            - up
            - down
            - steady
          title: Direction
          type: string
        high:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            The upper end of the paired test's 95% range for the move, in
            points.
          title: High
        low:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            The lower end of the paired test's 95% range for the move, in
            points.
          title: Low
        real:
          description: >-
            Whether the paired test over the prompt × engine cells both reads
            measured says the figure moved. The state is up or down only when
            this is true and the move has the sign of `delta`; otherwise it is
            steady and carries the signed `delta`.
          title: Real
          type: boolean
        state:
          default: calibrating
          description: >-
            The served comparison state, distinct from whether the figure is
            measured.
          enum:
            - up
            - down
            - steady
            - calibrating
            - first_report
            - not_comparable
          title: State
          type: string
      required:
        - state
        - delta
        - low
        - high
        - real
        - direction
        - baseline
        - cells_unpaired
        - compared_engines
      title: FigureChange
      type: object
    FigurePoint:
      properties:
        answers:
          title: Answers
          type: integer
        at:
          format: date-time
          title: At
          type: string
        break:
          anyOf:
            - $ref: '#/components/schemas/TrendBreak'
            - type: 'null'
          readOnly: true
        breaks:
          items:
            $ref: '#/components/schemas/KeyChange'
          title: Breaks
          type: array
        high:
          anyOf:
            - type: integer
            - type: 'null'
          title: High
        key:
          $ref: '#/components/schemas/ComparabilityKey'
        low:
          anyOf:
            - type: integer
            - type: 'null'
          title: Low
        scan_id:
          format: uuid
          title: Scan Id
          type: string
        state:
          title: State
          type: string
          x-extensible-enum:
            - measured
            - too_few_answers
            - calibrating
            - first_report
            - not_comparable
            - not_measured
            - pending
            - not_scored
        value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Value
      required:
        - scan_id
        - at
        - value
        - low
        - high
        - answers
        - state
        - key
        - breaks
        - break
      title: FigurePoint
      type: object
    Versus:
      description: |-
        One figure for the competitor beside the brand's own. `gap` is yours
        less theirs; it and `lead` are null where either side has no value.
      properties:
        gap:
          anyOf:
            - type: integer
            - type: 'null'
          description: Your value minus the competitor's, or null if either is unmeasured.
          title: Gap
        key:
          description: The figure, prompt or engine key.
          title: Key
          type: string
        label:
          description: The display name of the figure, prompt or engine.
          title: Label
          type: string
        lead:
          anyOf:
            - enum:
                - you
                - them
                - level
              type: string
            - type: 'null'
          description: Which brand leads, or null if either is unmeasured.
          title: Lead
        them:
          anyOf:
            - type: integer
            - type: 'null'
          description: The competitor's value, or null when unmeasured.
          title: Them
        you:
          anyOf:
            - type: integer
            - type: 'null'
          description: Your brand's value, or null when unmeasured.
          title: You
      required:
        - key
        - label
        - them
        - you
        - gap
        - lead
      title: Versus
      type: object
    Focus:
      properties:
        competitors:
          description: Starred competitors, oldest star first.
          items:
            $ref: '#/components/schemas/FocusItem'
          title: Competitors
          type: array
        limit:
          default: 3
          description: The most stars of each kind.
          title: Limit
          type: integer
        markets:
          description: Starred markets, oldest star first.
          items:
            $ref: '#/components/schemas/FocusItem'
          title: Markets
          type: array
        topics:
          description: Starred topics, oldest star first.
          items:
            $ref: '#/components/schemas/FocusItem'
          title: Topics
          type: array
      required:
        - topics
        - competitors
        - markets
        - limit
      title: Focus
      type: object
    V1TrendPoint:
      properties:
        answers:
          title: Answers
          type: integer
        at:
          format: date-time
          title: At
          type: string
        break:
          anyOf:
            - $ref: '#/components/schemas/TrendBreak'
            - type: 'null'
        high:
          anyOf:
            - type: integer
            - type: 'null'
          title: High
        low:
          anyOf:
            - type: integer
            - type: 'null'
          title: Low
        state:
          title: State
          type: string
          x-extensible-enum:
            - measured
            - too_few_answers
            - calibrating
            - first_report
            - not_comparable
            - not_measured
            - pending
            - not_scored
        value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Value
      required:
        - at
        - value
        - low
        - high
        - answers
        - state
        - break
      title: V1TrendPoint
      type: object
    VersusPage:
      description: |-
        One page of a pane's lost or won prompts, widest gap first, and how
        many there are.
      properties:
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        rows:
          items:
            $ref: '#/components/schemas/Versus'
          title: Rows
          type: array
        total:
          title: Total
          type: integer
      required:
        - rows
        - total
        - offset
        - limit
      title: VersusPage
      type: object
    Meta:
      properties:
        data_as_of:
          anyOf:
            - $ref: '#/components/schemas/DataAsOf'
            - type: 'null'
        last_attempt_failed:
          default: false
          description: The newest attempt failed; the last good result is displayed.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed response includes a partial report.
          title: Partial
          type: boolean
        query:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          title: Query
          type: object
        surfaces:
          additionalProperties:
            $ref: '#/components/schemas/SurfaceFreshness'
          description: >-
            Freshness by Command Center surface key. Each entry describes its
            own displayed result, including results without a scan.
          title: Surfaces
          type: object
        updating:
          default: false
          description: A newer result is being produced or is not yet displayed.
          title: Updating
          type: boolean
      required:
        - query
        - data_as_of
        - partial
        - updating
        - last_attempt_failed
        - surfaces
      title: Meta
      type: object
    V1CompetitorSites:
      examples:
        - changes: []
          limit: 20
          meta:
            data_as_of: null
            last_attempt_failed: false
            partial: false
            query: {}
            surfaces: {}
            updating: false
          next_cursor: null
          offset: 0
          reason: null
          rivals: []
          state: complete
          total: 0
      properties:
        changes:
          description: >-
            The week's moves, one per competitor and type of change, each
            standing for its shallowest page; with `change`, each page of that
            type. A file, such as a PDF, is never a page.
          items:
            $ref: '#/components/schemas/V1CompetitorSiteChange'
          title: Changes
          type: array
        limit:
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        reason:
          anyOf:
            - enum:
                - no_read
                - read_running
                - read_failed
              type: string
            - type: 'null'
          description: Why the read is incomplete; null when complete.
          title: Reason
        rivals:
          items:
            $ref: '#/components/schemas/V1CompetitorSite'
          title: Rivals
          type: array
        state:
          enum:
            - complete
            - pending
            - unavailable
          title: State
          type: string
        total:
          title: Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - state
        - reason
        - rivals
        - changes
      title: V1CompetitorSites
      type: object
    WorkRowResponse:
      description: |-
        One row of work, as the product reads it.

        The projection fields (`group`, `holder`, `stage`, `demand`) come from
        `project_work` and nothing else, so no consumer re-derives them from
        `state`. Severity and confidence are deliberately absent: priority is
        system-owned and neither is ever shown as a field (D12).
      properties:
        assignee:
          anyOf:
            - $ref: '#/components/schemas/AssigneeResponse'
            - type: 'null'
          description: The person accountable for the work.
        blocked_owner:
          anyOf:
            - type: string
            - type: 'null'
          description: Who the action waits on; null when not blocked.
          title: Blocked Owner
        brand_id:
          description: The brand this work belongs to.
          format: uuid
          readOnly: true
          title: Brand Id
          type: string
        check_again_on:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When to check blocked work again.
          title: Check Again On
        citation_count:
          default: 0
          description: Distinct engine and prompt citation pairs before the list cap.
          title: Citation Count
          type: integer
        completed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the action was marked done.
          title: Completed At
        created_at:
          description: When this work was created.
          format: date-time
          title: Created At
          type: string
        credit_cost:
          description: Content credits needed to dispatch this work.
          title: Credit Cost
          type: integer
        credits_spent:
          description: Content credits charged to this work and not refunded.
          title: Credits Spent
          type: integer
        delivered_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When the result went live, was sent or was published. Null on
            dismissed work.
          title: Delivered At
        demand:
          description: What the work is doing or waiting for.
          title: Demand
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          description: The finding behind the work; null when absent.
          title: Detail
        dispatchable:
          description: Whether Heralded can execute this work.
          title: Dispatchable
          type: boolean
        done_when:
          anyOf:
            - type: string
            - type: 'null'
          description: When the work is done; null on Heralded's own work.
          title: Done When
        draft_in_flight:
          anyOf:
            - enum:
                - drafting
                - redrafting
              type: string
            - type: 'null'
          description: Whether a first draft or redraft is being written.
          title: Draft In Flight
        ending:
          anyOf:
            - $ref: '#/components/schemas/EndingResponse'
            - type: 'null'
          description: >-
            How the task ended: its key, its words and when. Null while it is
            open.
        expected_impact_pts:
          anyOf:
            - type: integer
            - type: 'null'
          description: 'Always null: the expected gain is `gain`.'
          title: Expected Impact Pts
        first_citation:
          anyOf:
            - $ref: '#/components/schemas/FirstCitation'
            - type: 'null'
          description: First qualifying citation of the delivered page.
        focus:
          anyOf:
            - $ref: '#/components/schemas/FocusTag'
            - type: 'null'
          description: >-
            The starred topic or competitor the work serves, or outside your
            focus. Null when the brand has no starred topic or competitor, and
            on Heralded's own work.
        gain:
          anyOf:
            - $ref: '#/components/schemas/GainResponse'
            - type: 'null'
          description: >-
            The expected gain: its band and what the work aims at. Null on
            Heralded's own work.
        gate:
          anyOf:
            - enum:
                - approval
                - review
              type: string
            - type: 'null'
          description: The review or approval awaited; null otherwise.
          title: Gate
        grounds:
          anyOf:
            - $ref: '#/components/schemas/GroundsResponse'
            - type: 'null'
          description: >-
            What the work rests on; null on Heralded's own work and on work
            filed before actions carried their grounds.
        group:
          description: The current work group.
          enum:
            - new
            - your_input
            - dispatched
            - scheduled
            - waiting
            - settled
            - withdrawn
          title: Group
          type: string
        holder:
          anyOf:
            - enum:
                - you
                - heralded
                - waiting
              type: string
            - type: 'null'
          description: Who holds the next step; null when nobody does.
          title: Holder
        id:
          description: The action or recurring job id.
          format: uuid
          title: Id
          type: string
        impact_scale:
          anyOf:
            - type: string
            - type: 'null'
          description: The measure this action aims to improve.
          title: Impact Scale
        intent_bucket:
          anyOf:
            - type: string
            - type: 'null'
          description: The targeted prompt intent; null when absent.
          title: Intent Bucket
        issue_type:
          anyOf:
            - $ref: '#/components/schemas/IssueType'
            - enum:
                - daily_read
                - deep_read
                - inventory_crawl
                - detection_sweep
                - search_sweep
              type: string
          description: The kind of action or recurring job.
          title: Issue Type
        job:
          $ref: '#/components/schemas/JobResponse'
          description: The work's steps and available controls.
        kind_tag:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A tag on the kind of work, shown beside its state, such as
            Sponsored. Null on work that has none.
          title: Kind Tag
        looks_resolved_evidence:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Evidence for a resolution awaiting confirmation.
          title: Looks Resolved Evidence
        member:
          anyOf:
            - enum:
                - writer
                - publicist
                - engineer
                - analyst
              type: string
            - type: 'null'
          description: The responsible team member; null for setup and prompt replacements.
          title: Member
        not_seen_since_run:
          anyOf:
            - type: integer
            - type: 'null'
          description: The first report that stopped seeing the finding.
          title: Not Seen Since Run
        note:
          anyOf:
            - $ref: '#/components/schemas/TaskNote'
            - type: 'null'
          description: Task explanation with a live job step.
        outcome:
          anyOf:
            - enum:
                - verified_up
                - no_move
                - not_measured
                - dismissed
              type: string
            - type: 'null'
          description: How settled work ended; null while pending.
          title: Outcome
        paid_off_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When verification credited a positive measured gain. Null on
            dismissed work.
          title: Paid Off At
        placed_position:
          anyOf:
            - type: integer
            - type: 'null'
          description: The member's place in the proposal order.
          title: Placed Position
        platform:
          default: false
          description: Whether this is Heralded's recurring work.
          title: Platform
          type: boolean
        preview:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Up to 400 characters of draft opening, email recipient and subject,
            or planned change while waiting on you.
          title: Preview
        primary_verb:
          anyOf:
            - enum:
                - dispatch
                - take
                - done
                - defer
                - dismiss
                - confirm
                - reject
                - restore
                - block
                - unblock
                - reopen
              type: string
            - const: review
              type: string
            - type: 'null'
          description: The main offered action; null when none is offered.
          title: Primary Verb
        progress:
          anyOf:
            - $ref: '#/components/schemas/WorkProgressResponse'
            - type: 'null'
          description: The running job's progress.
        prompt_movement:
          anyOf:
            - type: string
            - type: 'null'
          description: Whether other work shares the prompt's movement.
          title: Prompt Movement
        repeat:
          anyOf:
            - enum:
                - daily
                - weekly
                - thrice_weekly
              type: string
            - type: 'null'
          description: The recurring job's schedule.
          title: Repeat
        return_group:
          anyOf:
            - enum:
                - new
                - your_input
                - dispatched
                - scheduled
                - waiting
                - settled
                - withdrawn
              type: string
            - type: 'null'
          description: The work group a return action resumes.
          title: Return Group
        route:
          description: The Command Center page this work concerns.
          enum:
            - home
            - actions
            - prompts
            - search
            - market
            - sources
            - content
            - perception
            - audit
          readOnly: true
          title: Route
          type: string
        run_state:
          anyOf:
            - enum:
                - scheduled
                - running
                - done
                - skipped
                - failed
                - stopped
              type: string
            - type: 'null'
          description: The recurring job's current run state.
          title: Run State
        scheduled_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The recurring job's next start.
          title: Scheduled At
        scheduled_for:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The scheduled start date; null when unset.
          title: Scheduled For
        secondary_verbs:
          description: Other offered actions, in menu order.
          items:
            enum:
              - dispatch
              - take
              - done
              - defer
              - dismiss
              - confirm
              - reject
              - restore
              - block
              - unblock
              - reopen
            type: string
          title: Secondary Verbs
          type: array
        segment:
          description: The work's configured segment label.
          title: Segment
          type: string
        settled_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When measurement or the decision settled.
          title: Settled At
        setup_link:
          anyOf:
            - $ref: '#/components/schemas/SetupLink'
            - type: 'null'
          description: Where to complete this setup task.
        stage:
          description: The work's observe, decide, do or verify stage.
          enum:
            - observe
            - decide
            - do
            - verify
          title: Stage
          type: string
        started_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The first time Heralded started this action. Null on dismissed work.
          title: Started At
        state:
          description: The action's lifecycle state.
          enum:
            - new
            - accepted
            - in_progress
            - blocked
            - looks_resolved
            - done
            - verified_no_move
            - deferred
            - dismissed
            - withdrawn
          title: State
          type: string
        target_entity:
          description: The page, prompt, source or check the work targets.
          title: Target Entity
          type: string
        target_type:
          anyOf:
            - type: string
            - type: 'null'
          description: What the target names; null when unknown.
          title: Target Type
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: The act this work proposes or delivers.
          title: Title
        tracked_domain_id:
          deprecated: true
          description: Deprecated alias of brand_id.
          format: uuid
          title: Tracked Domain Id
          type: string
        tracking:
          description: >-
            What Heralded tracks once the work is live: live, crawled, ranked,
            search_console, cited, moved.
          items:
            enum:
              - live
              - crawled
              - ranked
              - search_console
              - cited
              - moved
            type: string
          title: Tracking
          type: array
        updated_at:
          description: When this work last changed.
          format: date-time
          title: Updated At
          type: string
        verified_impact_pts:
          anyOf:
            - type: number
            - type: 'null'
          description: The measured gain credited to the action.
          title: Verified Impact Pts
        wait:
          anyOf:
            - $ref: '#/components/schemas/WaitResponse'
            - type: 'null'
          description: >-
            What the task waits for, on whom and until when. Null while it waits
            on nobody.
        waiting_since:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the current ask began; null outside your_input.
          title: Waiting Since
        write_language:
          anyOf:
            - type: string
            - type: 'null'
          description: The writing language code.
          title: Write Language
        write_language_locked:
          default: false
          description: Whether writing has locked the language.
          title: Write Language Locked
          type: boolean
        write_language_source:
          anyOf:
            - type: string
            - type: 'null'
          description: How the language was chosen.
          title: Write Language Source
      required:
        - id
        - tracked_domain_id
        - target_entity
        - write_language
        - write_language_source
        - write_language_locked
        - target_type
        - issue_type
        - segment
        - title
        - detail
        - state
        - group
        - holder
        - stage
        - demand
        - member
        - waiting_since
        - started_at
        - delivered_at
        - paid_off_at
        - preview
        - outcome
        - gate
        - settled_at
        - impact_scale
        - expected_impact_pts
        - verified_impact_pts
        - prompt_movement
        - blocked_owner
        - check_again_on
        - scheduled_for
        - scheduled_at
        - repeat
        - progress
        - platform
        - run_state
        - assignee
        - intent_bucket
        - looks_resolved_evidence
        - not_seen_since_run
        - placed_position
        - completed_at
        - created_at
        - updated_at
        - primary_verb
        - setup_link
        - secondary_verbs
        - return_group
        - job
        - note
        - credit_cost
        - credits_spent
        - dispatchable
        - draft_in_flight
        - grounds
        - done_when
        - tracking
        - first_citation
        - citation_count
        - gain
        - focus
        - kind_tag
        - ending
        - wait
        - brand_id
        - route
      title: WorkRowResponse
      type: object
    CompetitorCitedPage:
      properties:
        citations:
          title: Citations
          type: integer
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        url:
          title: Url
          type: string
      required:
        - url
        - title
        - citations
      title: CompetitorCitedPage
      type: object
    V1Period:
      properties:
        excluded_reports:
          title: Excluded Reports
          type: integer
        first_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: First Answer At
        last_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Answer At
        preset:
          enum:
            - 1w
            - 4w
            - 12w
            - all
          title: Preset
          type: string
        reports:
          title: Reports
          type: integer
      required:
        - preset
        - reports
        - first_answer_at
        - last_answer_at
        - excluded_reports
      title: V1Period
      type: object
    BrandProductCards:
      properties:
        average_position:
          anyOf:
            - type: number
            - type: 'null'
          description: Mean of each answer's best place for the brand.
          title: Average Position
        best_position:
          anyOf:
            - type: integer
            - type: 'null'
          description: Lowest organic place for the brand.
          title: Best Position
        in_product_cards:
          $ref: '#/components/schemas/ShoppingShare'
          description: Answers showing the brand divided by answers with organic cards.
        state:
          description: Whether the population's product cards were read.
          enum:
            - read
            - not_read
            - not_measured
          title: State
          type: string
        weeks:
          default: 0
          description: Weekly reports counted from the period measured as ecommerce.
          title: Weeks
          type: integer
      required:
        - weeks
        - state
        - in_product_cards
        - average_position
        - best_position
      title: BrandProductCards
      type: object
    RivalPagePane:
      properties:
        actions:
          items:
            $ref: '#/components/schemas/PaneAction'
          title: Actions
          type: array
        actions_total:
          default: 0
          description: Every live action about this subject, before the list is cut.
          title: Actions Total
          type: integer
        answers_link:
          anyOf:
            - $ref: '#/components/schemas/AnswersLink'
            - type: 'null'
        brand_key:
          title: Brand Key
          type: string
        brand_name:
          title: Brand Name
          type: string
        citation_evidence:
          default: complete
          enum:
            - complete
            - partial
            - unavailable
          title: Citation Evidence
          type: string
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Type
        engine_ids:
          items:
            type: string
          title: Engine Ids
          type: array
        engine_vocabulary:
          items:
            $ref: '#/components/schemas/EngineVocabulary'
          title: Engine Vocabulary
          type: array
        first_cited_at:
          anyOf:
            - type: string
            - type: 'null'
          title: First Cited At
        headline:
          title: Headline
          type: string
        measurement:
          description: >-
            How the page was measured. New measurement values may be added
            within v1.
          title: Measurement
          type: string
          x-extensible-enum:
            - measured
            - daily_only
            - unavailable
        next_step:
          anyOf:
            - $ref: '#/components/schemas/PaneAction'
            - type: 'null'
          description: >-
            The action `next_step_action_id` names, in the same shape as
            `actions`.
        next_step_action_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The highest-priority live action that awaits a member and whose verb
            the reader may press; null when there is none.
          title: Next Step Action Id
        prompt_count:
          description: Prompts represented by this row under the selected filters.
          title: Prompt Count
          type: integer
        prompts:
          items:
            $ref: '#/components/schemas/PanePrompt'
          title: Prompts
          type: array
        prompts_limit:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Maximum citing questions returned in this page; null for the
            complete selection.
          title: Prompts Limit
        prompts_offset:
          default: 0
          description: Citing questions skipped before this page.
          title: Prompts Offset
          type: integer
        question_trend:
          anyOf:
            - $ref: '#/components/schemas/MetricSeries'
            - type: 'null'
          description: >-
            Weekly counts of distinct tracked questions citing this page under
            the selected filters; null without a preview read.
        questions_delta:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Change in distinct citing questions against the preceding comparable
            period; null with missing or incomparable citation coverage.
          title: Questions Delta
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        total_prompt_count:
          description: All prompts for this competitor before paging.
          title: Total Prompt Count
          type: integer
        unavailable_scans:
          default: 0
          title: Unavailable Scans
          type: integer
        url:
          title: Url
          type: string
        why_it_works:
          anyOf:
            - type: string
            - type: 'null'
          title: Why It Works
        window:
          anyOf:
            - $ref: '#/components/schemas/WindowDescriptor'
            - type: 'null'
      required:
        - question_trend
        - questions_delta
        - answers_link
        - engine_vocabulary
        - window
        - url
        - title
        - brand_key
        - brand_name
        - content_type
        - headline
        - measurement
        - citation_evidence
        - unavailable_scans
        - prompt_count
        - total_prompt_count
        - engine_ids
        - first_cited_at
        - why_it_works
        - prompts
        - prompts_limit
        - prompts_offset
        - actions
        - actions_total
        - next_step_action_id
        - next_step
      title: RivalPagePane
      type: object
    ScoreMark:
      description: >-
        A score or figure from the figures read, with the band it is coloured

        by (#4259).


        `key` is the engine or the figure measured. `band` is the Heralded
        Score's

        band for the value, so a mark and a score read on one scale, and

        "Not measured" where no value is served, which includes a group under
        the

        minimum of answers. On a score, `answers` counts every answer the period

        read under the filters, including those a figure's own denominator
        leaves

        out.
      properties:
        answer_read_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer Read Id
        answers:
          title: Answers
          type: integer
        band:
          title: Band
          type: string
        key:
          title: Key
          type: string
        label:
          title: Label
          type: string
        state:
          title: State
          type: string
          x-extensible-enum:
            - measured
            - too_few_answers
            - calibrating
            - first_report
            - not_comparable
            - not_measured
            - pending
            - not_scored
        tooltip:
          anyOf:
            - type: string
            - type: 'null'
          title: Tooltip
        value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Value
      required:
        - key
        - label
        - value
        - state
        - band
        - answers
        - tooltip
        - answer_read_id
      title: ScoreMark
      type: object
    PromptTrend:
      description: A score's change, as the Trend column and the pane state it.
      properties:
        delta:
          anyOf:
            - type: integer
            - type: 'null'
          title: Delta
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        state:
          enum:
            - up
            - down
            - steady
            - not_comparable
            - calibrating
            - new
            - none
          title: State
          type: string
      required:
        - state
        - delta
        - label
      title: PromptTrend
      type: object
    V1CompetitorSiteDetail:
      properties:
        changes:
          description: >-
            The week's moves, one per competitor and type of change, each
            standing for its shallowest page; with `change`, each page of that
            type. A file, such as a PDF, is never a page.
          items:
            $ref: '#/components/schemas/V1CompetitorSiteChange'
          title: Changes
          type: array
        competitor:
          $ref: '#/components/schemas/V1CompetitorSite'
        limit:
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        state:
          enum:
            - complete
            - pending
            - unavailable
          title: State
          type: string
        total:
          title: Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - state
        - competitor
        - changes
      title: V1CompetitorSiteDetail
      type: object
    ValidationIssue:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Loc
          type: array
        msg:
          title: Msg
          type: string
        type:
          title: Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationIssue
      type: object
    RateLimitValues:
      properties:
        limit:
          title: Limit
          type: integer
        remaining:
          title: Remaining
          type: integer
        reset:
          title: Reset
          type: integer
        window:
          title: Window
          type: integer
      required:
        - limit
        - window
        - remaining
        - reset
      title: RateLimitValues
      type: object
    ComparisonPeriod:
      properties:
        first_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: First Answer At
        last_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Answer At
        reports:
          title: Reports
          type: integer
      required:
        - reports
        - first_answer_at
        - last_answer_at
      title: ComparisonPeriod
      type: object
    TrendBreak:
      properties:
        at:
          description: Date of the new baseline.
          format: date
          title: At
          type: string
        comparable:
          description: Whether the changed instrument still permits comparison.
          title: Comparable
          type: boolean
        engines_added:
          description: Engines added at this baseline.
          items:
            type: string
          title: Engines Added
          type: array
        engines_removed:
          description: Engines removed at this baseline.
          items:
            type: string
          title: Engines Removed
          type: array
        parts:
          description: Instrument parts that changed.
          items:
            type: string
            x-extensible-enum:
              - engines
              - language
              - market
              - score_version
              - answer_pack_version
              - understood_measure
              - sells_to
              - shopping_pack_version
          title: Parts
          type: array
      required:
        - at
        - parts
        - engines_added
        - engines_removed
        - comparable
      title: TrendBreak
      type: object
    KeyChange:
      description: One part of the instrument that changed between two reads.
      properties:
        added:
          default: []
          items:
            type: string
          title: Added
          type: array
        part:
          title: Part
          type: string
          x-extensible-enum:
            - engines
            - language
            - market
            - score_version
            - answer_pack_version
            - understood_measure
            - sells_to
            - shopping_pack_version
        removed:
          default: []
          items:
            type: string
          title: Removed
          type: array
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
      required:
        - part
        - added
        - removed
        - value
      title: KeyChange
      type: object
    ComparabilityKey:
      description: |-
        The instrument one read was taken with. A part that cannot be told is
        None, and a None part never breaks a series: a run whose answers the
        retention sweep took no longer says which engines it asked.
      properties:
        answer_pack_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Answer Pack Version
        ecommerce:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            Whether the run measured the brand as ecommerce. A change never
            breaks a series; null where unknown.
          title: Ecommerce
        engines:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Engines
        keyword_set_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Keyword Set Hash
        markets:
          additionalProperties:
            type: string
          default: {}
          title: Markets
          type: object
        passes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Passes
        score_version:
          title: Score Version
          type: string
        sells_to:
          anyOf:
            - enum:
                - businesses
                - consumers
              type: string
            - type: 'null'
          description: >-
            Who the run measured the brand as selling to. A change starts a new
            series; null where unknown.
          title: Sells To
        shopping_pack_version:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The version of the reading that judged the report's product cards.
            Only product card figures compare it; null where the report read no
            product cards.
          title: Shopping Pack Version
        sides:
          anyOf:
            - items:
                enum:
                  - ai
                  - search
                type: string
              type: array
            - type: 'null'
          title: Sides
        understood_measure:
          anyOf:
            - enum:
                - statements
                - parts
              type: string
            - type: 'null'
          description: >-
            How the report read Understood: each profile statement whole, or
            part by part. Only Understood's trend and change compare it; null
            where unknown.
          title: Understood Measure
      required:
        - engines
        - markets
        - score_version
        - answer_pack_version
        - passes
        - sides
        - keyword_set_hash
        - understood_measure
        - sells_to
        - ecommerce
        - shopping_pack_version
      title: ComparabilityKey
      type: object
    FocusItem:
      properties:
        audience_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Audience UUID; null for All buyers.
          title: Audience Id
        id:
          description: The tracked topic id, competitor key or market profile id.
          title: Id
          type: string
        kind:
          description: topic, competitor or market.
          enum:
            - topic
            - competitor
            - market
          title: Kind
          type: string
        market:
          anyOf:
            - type: string
            - type: 'null'
          description: The topic's or focused market's code.
          title: Market
        name:
          description: The topic's, competitor's or market's name.
          title: Name
          type: string
        tracked:
          description: >-
            False once the tracked topic is archived, its market is retired, or
            the competitor is no longer tracked; the star stays until removed.
          title: Tracked
          type: boolean
      required:
        - kind
        - id
        - name
        - tracked
        - market
        - audience_id
      title: FocusItem
      type: object
    DataAsOf:
      properties:
        completed_at:
          format: date-time
          title: Completed At
          type: string
        id:
          format: uuid
          title: Id
          type: string
      required:
        - id
        - completed_at
      title: DataAsOf
      type: object
    JsonValue: {}
    SurfaceFreshness:
      properties:
        as_of:
          anyOf:
            - $ref: '#/components/schemas/SurfaceAsOf'
            - type: 'null'
          description: The result displayed here.
        last_attempt_failed:
          default: false
          description: The newest attempt failed; any displayed result is retained.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed report is partial.
          title: Partial
          type: boolean
        updating:
          default: false
          description: A newer attempt exists whose result is not yet displayed.
          title: Updating
          type: boolean
      required:
        - as_of
        - partial
        - updating
        - last_attempt_failed
      title: SurfaceFreshness
      type: object
    V1CompetitorSiteChange:
      properties:
        after:
          anyOf:
            - $ref: '#/components/schemas/V1CompetitorSiteSnapshot'
            - type: 'null'
          description: The changed week's stored values, when available.
        before:
          anyOf:
            - $ref: '#/components/schemas/V1CompetitorSiteSnapshot'
            - type: 'null'
          description: The previous stored week's values, when available.
        change:
          enum:
            - new_page
            - removed_page
            - homepage_changed
            - pricing_changed
            - key_page_changed
          title: Change
          type: string
        host:
          title: Host
          type: string
        insight:
          anyOf:
            - $ref: '#/components/schemas/ServedInsight'
            - type: 'null'
          description: >-
            The work that fits the move, a comparison page against the
            competitor, and the work filed on it; null outside a brand's own
            read.
        key:
          title: Key
          type: string
        name:
          title: Name
          type: string
        observed_at:
          format: date-time
          title: Observed At
          type: string
        screenshot_url:
          anyOf:
            - type: string
            - type: 'null'
          description: The current homepage screenshot, never an earlier screenshot.
          title: Screenshot Url
        url:
          title: Url
          type: string
        week:
          format: date
          title: Week
          type: string
      required:
        - key
        - name
        - host
        - url
        - change
        - week
        - observed_at
        - before
        - after
        - screenshot_url
        - insight
      title: V1CompetitorSiteChange
      type: object
    V1CompetitorSite:
      properties:
        above_the_fold:
          anyOf:
            - $ref: '#/components/schemas/V1AboveTheFold'
            - type: 'null'
        activity:
          items:
            $ref: '#/components/schemas/V1CompetitorActivity'
          title: Activity
          type: array
        categories:
          items:
            $ref: '#/components/schemas/V1CompetitorCategory'
          title: Categories
          type: array
        checks:
          anyOf:
            - additionalProperties:
                type: boolean
              type: object
            - type: 'null'
          title: Checks
        checks_met:
          anyOf:
            - type: integer
            - type: 'null'
          title: Checks Met
        host:
          title: Host
          type: string
        key:
          title: Key
          type: string
        key_pages:
          items:
            $ref: '#/components/schemas/V1CompetitorKeyPage'
          title: Key Pages
          type: array
        key_pages_changed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Key Pages Changed
        name:
          title: Name
          type: string
        new:
          anyOf:
            - type: integer
            - type: 'null'
          title: New
        pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Pages
        pricing:
          anyOf:
            - $ref: '#/components/schemas/V1CompetitorPricing'
            - type: 'null'
        proof:
          anyOf:
            - enum:
                - 'yes'
                - 'no'
                - unclear
              type: string
            - type: 'null'
          title: Proof
        removed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Removed
        sameness:
          anyOf:
            - type: number
            - type: 'null'
          description: Copy similarity, from 0 to 1.
          title: Sameness
        screenshot_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Screenshot Url
        unmeasured:
          additionalProperties:
            type: string
          title: Unmeasured
          type: object
        url:
          title: Url
          type: string
        week:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Week
      required:
        - key
        - name
        - host
        - url
        - screenshot_url
        - above_the_fold
        - proof
        - sameness
        - pricing
        - week
        - pages
        - new
        - removed
        - key_pages_changed
        - checks
        - checks_met
        - key_pages
        - categories
        - activity
        - unmeasured
      title: V1CompetitorSite
      type: object
    AssigneeResponse:
      properties:
        id:
          format: uuid
          title: Id
          type: string
        initials:
          title: Initials
          type: string
        name:
          title: Name
          type: string
      required:
        - id
        - name
        - initials
      title: AssigneeResponse
      type: object
    EndingResponse:
      description: How an ended task ended.
      properties:
        at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When it ended.
          title: At
        key:
          description: >-
            no_reply, no_reply_recorded, declined, opted_out, stopped, not_now,
            too_much_work, not_relevant or already_done.
          title: Key
          type: string
        label:
          description: The ending in words, such as No reply or Not relevant.
          title: Label
          type: string
      required:
        - key
        - label
        - at
      title: EndingResponse
      type: object
    FirstCitation:
      properties:
        answer_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Answer to open; null when no answer id can be recovered.
          title: Answer Id
        cited_at:
          description: When the citing answer was observed, after publication.
          format: date-time
          title: Cited At
          type: string
        display_name:
          description: Current engine name from the engine registry.
          title: Display Name
          type: string
        engine_id:
          description: Engine that cited the published page.
          title: Engine Id
          type: string
        mark_id:
          description: Engine id used to choose its visual mark.
          readOnly: true
          title: Mark Id
          type: string
        prompt:
          description: Prompt wording in the citing answer.
          title: Prompt
          type: string
        prompt_uid:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Stable prompt id; null on older evidence without one.
          title: Prompt Uid
        scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Read that observed this citation; null when not recorded.
          title: Scan Id
      required:
        - engine_id
        - display_name
        - prompt
        - prompt_uid
        - answer_id
        - cited_at
        - scan_id
        - mark_id
      title: FirstCitation
      type: object
    FocusTag:
      description: The focus a piece of work serves.
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          description: The topic id or competitor key; null outside your focus.
          title: Id
        kind:
          description: A starred topic, a starred competitor, or outside your focus.
          enum:
            - topic
            - competitor
            - outside
          title: Kind
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: Its name; null outside your focus.
          title: Name
      required:
        - kind
        - id
        - name
      title: FocusTag
      type: object
    GainResponse:
      description: The gain a piece of work is expected to bring.
      properties:
        aims_at:
          description: What the work aims at.
          title: Aims At
          type: string
        band:
          anyOf:
            - enum:
                - high
                - medium
                - low
              type: string
            - type: 'null'
          description: >-
            How far the work is expected to move what it aims at: high, medium
            or low. Null where Heralded does not estimate it, on work a member
            asked for.
          title: Band
      required:
        - band
        - aims_at
      title: GainResponse
      type: object
    GroundsResponse:
      description: What a piece of work rests on (#6065).
      properties:
        cause:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The leading observation. Null on work a member asked for with no
            finding or evidence behind it.
          title: Cause
        evidence:
          description: >-
            The dated observations the work rests on, besides the one the cause
            states.
          items:
            $ref: '#/components/schemas/Evidence'
          title: Evidence
          type: array
        guidance:
          description: >-
            The publisher guidance a best-practice action rests on, with the
            date Heralded last checked it. Empty on other grounds.
          items:
            $ref: '#/components/schemas/Guidance'
          title: Guidance
          type: array
        kind:
          description: >-
            your_data: diagnosed from the brand's own reads; category_data: what
            is cited and ranked for rivals and the category; best_practice:
            known to work, with the guidance it rests on; you_asked: a member
            asked for it.
          enum:
            - your_data
            - category_data
            - best_practice
            - you_asked
          title: Kind
          type: string
        observed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The observation stated by the cause, when its date is known.
          title: Observed At
        targets:
          description: The prompt or keyword results this work targets.
          items:
            $ref: '#/components/schemas/Target'
          title: Targets
          type: array
        why:
          anyOf:
            - type: string
            - type: 'null'
          description: Why this evidence calls for this work.
          title: Why
      required:
        - kind
        - cause
        - evidence
        - guidance
      title: GroundsResponse
      type: object
    IssueType:
      enum:
        - modify_content
        - create_content
        - add_keyword
        - pitch_to_source
        - request_correction
        - close_competitor_gap
        - technical_fix
        - setup
      title: IssueType
      type: string
    JobResponse:
      description: |-
        What this row's task is as a job (#2429): every stage, where it stands,
        what happens next and what the button does. Composed per kind by
        `app.actions.jobs.describe_job`; no surface keeps a second table.
      properties:
        control:
          enum:
            - dispatch
            - act
            - take
          title: Control
          type: string
        current:
          anyOf:
            - type: string
            - type: 'null'
          title: Current
        endings:
          description: >-
            The ways you may end the task in its current state, an ending that
            answers its wait first; empty where none is offered.
          items:
            $ref: '#/components/schemas/EndingChoiceResponse'
          title: Endings
          type: array
        failure:
          anyOf:
            - type: string
            - type: 'null'
          description: Why the piece failed; null unless it did.
          title: Failure
        kind:
          title: Kind
          type: string
        next_step:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Step
        runs_steps:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Runs Steps
        stages:
          items:
            $ref: '#/components/schemas/JobStageResponse'
          title: Stages
          type: array
        step:
          anyOf:
            - $ref: '#/components/schemas/JobStepResponse'
            - type: 'null'
        stopped_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Stopped At
      required:
        - kind
        - stages
        - current
        - stopped_at
        - failure
        - next_step
        - control
        - runs_steps
        - step
        - endings
      title: JobResponse
      type: object
    TaskNote:
      properties:
        how_well_know:
          title: How Well Know
          type: string
        short_form:
          title: Short Form
          type: string
        what_i_need_from_you:
          title: What I Need From You
          type: string
        what_ill_do:
          title: What Ill Do
          type: string
        whats_happening:
          title: Whats Happening
          type: string
        why_it_matters:
          anyOf:
            - type: string
            - type: 'null'
          title: Why It Matters
      required:
        - whats_happening
        - why_it_matters
        - what_ill_do
        - what_i_need_from_you
        - how_well_know
        - short_form
      title: TaskNote
      type: object
    WorkProgressResponse:
      description: |-
        How far an executing read has got (#2446): engines answered of the
        engines asked. The words are the row's; the pips are the client's.
      properties:
        done:
          title: Done
          type: integer
        total:
          title: Total
          type: integer
        unit:
          title: Unit
          type: string
      required:
        - done
        - total
        - unit
      title: WorkProgressResponse
      type: object
    SetupLink:
      properties:
        href:
          title: Href
          type: string
        label:
          title: Label
          type: string
      required:
        - label
        - href
      title: SetupLink
      type: object
    WaitResponse:
      description: What the task waits for.
      properties:
        acts:
          description: 'Who acts when the wait is over: heralded or member.'
          enum:
            - heralded
            - member
          title: Acts
          type: string
        due_on:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When the wait is due; null when it has no date.
          title: Due On
        due_source:
          anyOf:
            - enum:
                - given
                - default
                - ours
              type: string
            - type: 'null'
          description: >-
            Where the date came from: given by them, Heralded's default, or our
            schedule; null without a date.
          title: Due Source
        kind:
          description: >-
            answer to an email of ours, agreed on a date they gave, queued
            behind another task to the same contact, asked whether they replied,
            or blocked on a third party you named.
          enum:
            - answer
            - agreed
            - queued
            - asked
            - blocked
          title: Kind
          type: string
        'on':
          description: Who the task waits on.
          title: 'On'
          type: string
        since:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the wait began.
          title: Since
      required:
        - kind
        - 'on'
        - due_on
        - due_source
        - acts
        - since
      title: WaitResponse
      type: object
    ShoppingShare:
      description: A share of answers over its own denominator, with its 95% range.
      properties:
        denominator:
          description: The count it is a share of.
          title: Denominator
          type: integer
        high:
          anyOf:
            - type: number
            - type: 'null'
          description: The 95% range's high end; null with no denominator.
          title: High
        low:
          anyOf:
            - type: number
            - type: 'null'
          description: The 95% range's low end; null with no denominator.
          title: Low
        numerator:
          description: The figure's own count.
          title: Numerator
          type: integer
        value:
          anyOf:
            - type: number
            - type: 'null'
          description: The share in [0, 1]; null with no denominator.
          title: Value
      required:
        - value
        - low
        - high
        - numerator
        - denominator
      title: ShoppingShare
      type: object
    PaneAction:
      description: The response the rival already has queued, as the pane shows it.
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
        expected_impact_pts:
          anyOf:
            - type: integer
            - type: 'null'
          description: Always null.
          title: Expected Impact Pts
        id:
          title: Id
          type: string
        impact_scale:
          anyOf:
            - type: string
            - type: 'null'
          title: Impact Scale
        status:
          title: Status
          type: string
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
      required:
        - id
        - title
        - detail
        - status
        - expected_impact_pts
        - impact_scale
      title: PaneAction
      type: object
    EngineVocabulary:
      properties:
        display_name:
          title: Display Name
          type: string
        engine_id:
          title: Engine Id
          type: string
        sort_order:
          title: Sort Order
          type: integer
      required:
        - engine_id
        - display_name
        - sort_order
      title: EngineVocabulary
      type: object
    PanePrompt:
      properties:
        answer_read_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer Read Id
        intent:
          anyOf:
            - type: string
            - type: 'null'
          title: Intent
        prompt_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Type
        prompt_uid:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Uid
        query_id:
          title: Query Id
          type: string
        search_volume:
          anyOf:
            - type: integer
            - type: 'null'
          title: Search Volume
        text:
          title: Text
          type: string
        winner_brand_keys:
          items:
            type: string
          title: Winner Brand Keys
          type: array
      required:
        - query_id
        - prompt_uid
        - text
        - intent
        - prompt_type
        - search_volume
        - winner_brand_keys
        - answer_read_id
      title: PanePrompt
      type: object
    MetricSeries:
      properties:
        introduced_at_run:
          anyOf:
            - type: integer
            - type: 'null'
          title: Introduced At Run
        metric:
          title: Metric
          type: string
        points:
          items:
            $ref: '#/components/schemas/SeriesPoint'
          title: Points
          type: array
      required:
        - metric
        - introduced_at_run
        - points
      title: MetricSeries
      type: object
    WindowDescriptor:
      properties:
        choice:
          enum:
            - latest
            - 4w
            - 12w
          title: Choice
          type: string
        first_read_at:
          anyOf:
            - type: string
            - type: 'null'
          title: First Read At
        last_read_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Read At
        reads:
          title: Reads
          type: integer
      required:
        - choice
        - reads
        - first_read_at
        - last_read_at
      title: WindowDescriptor
      type: object
    SurfaceAsOf:
      properties:
        at:
          description: When the displayed result was measured.
          format: date-time
          title: At
          type: string
        scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The result's scan, null for a timestamp-only result.
          title: Scan Id
      required:
        - scan_id
        - at
      title: SurfaceAsOf
      type: object
    V1CompetitorSiteSnapshot:
      properties:
        checks:
          anyOf:
            - additionalProperties:
                type: boolean
              type: object
            - type: 'null'
          description: The stored homepage's offer, audience, reason and next-step checks.
          title: Checks
        headline:
          anyOf:
            - type: string
            - type: 'null'
          description: The stored homepage headline.
          title: Headline
        pricing:
          anyOf:
            - $ref: '#/components/schemas/V1CompetitorPricing'
            - type: 'null'
          description: The stored pricing reading for this page.
        week:
          description: The detection week this stored reading describes.
          format: date
          title: Week
          type: string
      required:
        - week
        - headline
        - checks
        - pricing
      title: V1CompetitorSiteSnapshot
      type: object
    ServedInsight:
      properties:
        id:
          description: >-
            Stable across reads: `finding:<id>`, `check:<page>:<check>`,
            `page:<claim>:<url>`, `source:<domain>`, `rates:<domain>`,
            `opinion:<id>`, `topic:<topic>:<segment>`,
            `move:<competitor>:<change>:<week>:<url>`, `question:<prompt>` or
            `product:<product>`.
          title: Id
          type: string
        kinds:
          description: The kinds of work that fit it; empty when none does.
          items:
            $ref: '#/components/schemas/InsightKind'
          title: Kinds
          type: array
        work:
          anyOf:
            - $ref: '#/components/schemas/InsightWork'
            - type: 'null'
          description: >-
            The work filed from it, which filing it again returns; null when
            none is.
      required:
        - id
        - kinds
        - work
      title: ServedInsight
      type: object
    V1AboveTheFold:
      description: What a visitor sees before scrolling, read off the page's screenshot.
      properties:
        audience:
          anyOf:
            - type: string
            - type: 'null'
          description: Who it says it is for.
          title: Audience
        call_to_action:
          anyOf:
            - type: string
            - type: 'null'
          description: The hero's next step.
          title: Call To Action
        captured_at:
          format: date-time
          title: Captured At
          type: string
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
        cta_actionable:
          enum:
            - pass
            - fail
            - unclear
          title: Cta Actionable
          type: string
        design:
          $ref: '#/components/schemas/V1Design'
        header_action:
          anyOf:
            - type: string
            - type: 'null'
          title: Header Action
        headline:
          anyOf:
            - type: string
            - type: 'null'
          title: Headline
        headline_specific:
          enum:
            - pass
            - fail
            - unclear
          title: Headline Specific
          type: string
        hero_action_late:
          anyOf:
            - type: boolean
            - type: 'null'
          description: The hero's action appeared only after load; null where not compared.
          title: Hero Action Late
        load_screenshot_url:
          anyOf:
            - type: string
            - type: 'null'
          description: The screenshot at load.
          title: Load Screenshot Url
        offer:
          anyOf:
            - type: string
            - type: 'null'
          description: What it says is sold; null where it does not say.
          title: Offer
        proof_on_screen:
          title: Proof On Screen
          type: boolean
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: Why choose it.
          title: Reason
        regions:
          $ref: '#/components/schemas/V1Regions'
          description: Where the headline and action sit, as fractions.
        screenshot_url:
          anyOf:
            - type: string
            - type: 'null'
          description: The screenshot 3 s after load.
          title: Screenshot Url
        url:
          title: Url
          type: string
      required:
        - url
        - screenshot_url
        - load_screenshot_url
        - captured_at
        - category
        - headline
        - offer
        - audience
        - reason
        - call_to_action
        - header_action
        - hero_action_late
        - regions
        - proof_on_screen
        - design
        - headline_specific
        - cta_actionable
      title: V1AboveTheFold
      type: object
    V1CompetitorActivity:
      properties:
        key_pages_changed:
          title: Key Pages Changed
          type: integer
        new_pages:
          title: New Pages
          type: integer
        removed_pages:
          title: Removed Pages
          type: integer
        week:
          format: date
          title: Week
          type: string
      required:
        - week
        - new_pages
        - key_pages_changed
        - removed_pages
      title: V1CompetitorActivity
      type: object
    V1CompetitorCategory:
      properties:
        count:
          title: Count
          type: integer
        group:
          title: Group
          type: string
        name:
          title: Name
          type: string
      required:
        - name
        - group
        - count
      title: V1CompetitorCategory
      type: object
    V1CompetitorKeyPage:
      properties:
        changed:
          title: Changed
          type: boolean
        checked:
          title: Checked
          type: boolean
        kind:
          enum:
            - homepage
            - pricing
            - key
          title: Kind
          type: string
        url:
          title: Url
          type: string
      required:
        - url
        - kind
        - checked
        - changed
      title: V1CompetitorKeyPage
      type: object
    V1CompetitorPricing:
      properties:
        plans:
          anyOf:
            - items:
                $ref: '#/components/schemas/V1CompetitorPlan'
              type: array
            - type: 'null'
          description: >-
            Prices as the page states them; null where pricing could not be
            read.
          title: Plans
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        state:
          enum:
            - plans
            - not_readable
            - not_found
          title: State
          type: string
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
      required:
        - state
        - reason
        - url
        - plans
      title: V1CompetitorPricing
      type: object
    Evidence:
      properties:
        fact:
          title: Fact
          type: string
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        measure:
          anyOf:
            - type: string
            - type: 'null'
          description: Stable measure whose newest observation replaces an older one.
          title: Measure
        observed_at:
          format: date-time
          title: Observed At
          type: string
        url:
          anyOf:
            - type: string
            - type: 'null'
          description: The cited page supporting this observation.
          title: Url
      required:
        - observed_at
        - fact
      title: Evidence
      type: object
    Guidance:
      description: The publisher guidance a best-practice play rests on.
      properties:
        checked_on:
          description: When Heralded last read the guidance.
          format: date
          title: Checked On
          type: string
        publisher:
          title: Publisher
          type: string
        title:
          title: Title
          type: string
        url:
          title: Url
          type: string
      required:
        - publisher
        - title
        - url
        - checked_on
      title: Guidance
      type: object
    Target:
      properties:
        engine:
          anyOf:
            - type: string
            - type: 'null'
          title: Engine
        kind:
          enum:
            - prompt
            - keyword
          title: Kind
          type: string
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
        metric:
          enum:
            - recommended
            - rank
          title: Metric
          type: string
        uid:
          format: uuid
          title: Uid
          type: string
      required:
        - kind
        - uid
        - engine
        - metric
        - language
      title: Target
      type: object
    EndingChoiceResponse:
      description: One way the member may end the task, or the wait it stands in.
      properties:
        confirm:
          anyOf:
            - $ref: '#/components/schemas/EndingConfirmResponse'
            - type: 'null'
          description: The confirmation it asks for first; null when none.
        key:
          description: >-
            The ending: no_reply, declined, stopped, no_longer_waiting, or skip,
            which lets the follow-up due after a missed date go unsent.
          title: Key
          type: string
        label:
          description: The words on the control.
          title: Label
          type: string
        verb:
          description: >-
            What it sends: the dismiss or unblock verb, close, which closes the
            task's emails with `key` as the reason, or skip, which skips the
            follow-up due and waits again. The verbs grow with the kinds of
            work: offer an unknown one nowhere.
          title: Verb
          type: string
          x-extensible-enum:
            - dismiss
            - unblock
            - close
            - skip
      required:
        - key
        - label
        - verb
        - confirm
      title: EndingChoiceResponse
      type: object
    JobStageResponse:
      properties:
        doer:
          enum:
            - heralded
            - member
            - watch
          title: Doer
          type: string
        done_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Done At
        key:
          title: Key
          type: string
        label:
          title: Label
          type: string
        lane:
          default: main
          description: >-
            Which run of the steps the stage sits in: main, or article for the
            article an outreach agreement needs, which runs beside the emails.
          enum:
            - main
            - article
          title: Lane
          type: string
        line:
          title: Line
          type: string
        status:
          default: ahead
          description: >-
            Where the stage stands: done, now, ahead, or ended, the stage an
            ended task had reached when it ended.
          enum:
            - done
            - now
            - ahead
            - ended
          title: Status
          type: string
      required:
        - key
        - label
        - line
        - doer
        - done_at
        - status
        - lane
      title: JobStageResponse
      type: object
    JobStepResponse:
      description: |-
        One stage the member may run alone where the area would run the
        whole job: `hold_at_gate` on the dispatch request stops it at the
        approval gate (#2429).
      properties:
        hold_at_gate:
          title: Hold At Gate
          type: boolean
        label:
          title: Label
          type: string
      required:
        - label
        - hold_at_gate
      title: JobStepResponse
      type: object
    SeriesPoint:
      properties:
        break:
          anyOf:
            - $ref: '#/components/schemas/TrendBreak'
            - type: 'null'
          readOnly: true
        breaks:
          default: []
          items:
            $ref: '#/components/schemas/KeyChange'
          title: Breaks
          type: array
        completed_at:
          title: Completed At
          type: string
        degraded:
          default: false
          title: Degraded
          type: boolean
        key:
          anyOf:
            - $ref: '#/components/schemas/ComparabilityKey'
            - type: 'null'
        measured_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Measured Domain
        prompts_changed:
          default: false
          title: Prompts Changed
          type: boolean
        run_number:
          title: Run Number
          type: integer
        value:
          anyOf:
            - type: number
            - type: integer
            - type: 'null'
          title: Value
      required:
        - run_number
        - completed_at
        - value
        - degraded
        - measured_domain
        - key
        - breaks
        - prompts_changed
        - break
      title: SeriesPoint
      type: object
    InsightKind:
      properties:
        credits:
          description: Content credits starting the work spends; 0 when free.
          title: Credits
          type: integer
        play:
          description: The kind of work, a play key. Send it as `kind` to file it.
          title: Play
          type: string
        title:
          description: The work as it would be filed.
          title: Title
          type: string
      required:
        - play
        - title
        - credits
      title: InsightKind
      type: object
    InsightWork:
      properties:
        id:
          description: Open it with get_action or /v1/actions/{id}.
          format: uuid
          title: Id
          type: string
        state:
          description: The action's state.
          title: State
          type: string
        status:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The customer-facing stage from the work projection; null when not
            loaded.
          title: Status
      required:
        - id
        - state
        - status
      title: InsightWork
      type: object
    V1Design:
      properties:
        clutter:
          $ref: '#/components/schemas/V1ScreenCheck'
        fits_buyer:
          $ref: '#/components/schemas/V1ScreenCheck'
        generated_look:
          $ref: '#/components/schemas/V1ScreenCheck'
        hierarchy:
          $ref: '#/components/schemas/V1ScreenCheck'
        looks_current:
          $ref: '#/components/schemas/V1ScreenCheck'
        readability:
          $ref: '#/components/schemas/V1ScreenCheck'
      required:
        - hierarchy
        - clutter
        - readability
        - looks_current
        - fits_buyer
        - generated_look
      title: V1Design
      type: object
    V1Regions:
      properties:
        call_to_action:
          anyOf:
            - $ref: '#/components/schemas/V1Region'
            - type: 'null'
        headline:
          anyOf:
            - $ref: '#/components/schemas/V1Region'
            - type: 'null'
      required:
        - headline
        - call_to_action
      title: V1Regions
      type: object
    V1CompetitorPlan:
      properties:
        name:
          title: Name
          type: string
        period:
          anyOf:
            - type: string
            - type: 'null'
          title: Period
        price:
          title: Price
          type: string
      required:
        - name
        - price
        - period
      title: V1CompetitorPlan
      type: object
    EndingConfirmResponse:
      properties:
        confirm_label:
          description: The words on the button that confirms it.
          title: Confirm Label
          type: string
        question:
          description: What the confirmation asks before the ending goes.
          title: Question
          type: string
      required:
        - question
        - confirm_label
      title: EndingConfirmResponse
      type: object
    V1ScreenCheck:
      properties:
        verdict:
          enum:
            - pass
            - fail
            - unsure
          title: Verdict
          type: string
        why:
          title: Why
          type: string
      required:
        - verdict
        - why
      title: V1ScreenCheck
      type: object
    V1Region:
      properties:
        h:
          title: H
          type: number
        w:
          title: W
          type: number
        x:
          title: X
          type: number
        'y':
          title: 'Y'
          type: number
      required:
        - x
        - 'y'
        - w
        - h
      title: V1Region
      type: object
  securitySchemes:
    apiKey:
      description: 'An API key, sent as `Authorization: Bearer hrld_...`.'
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.