> ## 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 Action

> One action as its pane reads it: state, verbs, job, costs, assignee, steps, thread,
draft versions, application, the scans that raised it and evidence, with its grounds,
done-when, what Heralded tracks and the trail of what happened since delivery. `as_of`
pins the evidence to a scan; the work itself is live.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/actions/{action_id}
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/actions/{action_id}:
    get:
      tags:
        - v1
      summary: Get Action
      description: >-
        One action as its pane reads it: state, verbs, job, costs, assignee,
        steps, thread,

        draft versions, application, the scans that raised it and evidence, with
        its grounds,

        done-when, what Heralded tracks and the trail of what happened since
        delivery. `as_of`

        pins the evidence to a scan; the work itself is live.
      operationId: getAction
      parameters:
        - description: An action id from list_actions.
          in: path
          name: action_id
          required: true
          schema:
            description: An action id from list_actions.
            format: uuid
            title: Action Id
            type: string
        - description: Section page size, at most 100.
          in: query
          name: limit
          required: false
          schema:
            default: 5
            description: Section page size, at most 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: Include all sections; false returns a compact preview.
          in: query
          name: with_details
          required: false
          schema:
            default: true
            description: Include all sections; false returns a compact preview.
            title: With Details
            type: boolean
        - description: >-
            Include the caller's visible activity names, kit, rewrite allowance
            and whether the work is assigned to them.
          in: query
          name: with_viewer
          required: false
          schema:
            default: false
            description: >-
              Include the caller's visible activity names, kit, rewrite
              allowance and whether the work is assigned to them.
            title: With Viewer
            type: boolean
        - description: Read one paged section instead of all detail.
          in: query
          name: section
          required: false
          schema:
            anyOf:
              - enum:
                  - activity
                  - pages
                  - targets
                  - versions
                  - evidence
                  - sources
                  - emails
                type: string
              - type: 'null'
            description: Read one paged section instead of all detail.
            title: Section
        - description: >-
            With `section=activity`, page only the events of this step, by its
            `key`.
          in: query
          name: step
          required: false
          schema:
            anyOf:
              - maxLength: 40
                type: string
              - type: 'null'
            description: >-
              With `section=activity`, page only the events of this step, by its
              `key`.
            title: Step
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ActionDetail'
          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:
    V1ActionDetail:
      properties:
        application:
          anyOf:
            - $ref: '#/components/schemas/V1ActionApplication'
            - type: 'null'
        asset:
          anyOf:
            - $ref: '#/components/schemas/V1Asset'
            - type: 'null'
          description: The current asset, null before one has been made.
        assignee:
          anyOf:
            - $ref: '#/components/schemas/AssigneeResponse'
            - type: 'null'
        blocked_owner:
          anyOf:
            - type: string
            - type: 'null'
          title: Blocked Owner
        brand_id:
          format: uuid
          title: Brand Id
          type: string
        check_again_on:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Check Again On
        checklist:
          description: >-
            The steps you follow where Heralded drafts and applies nothing: a
            site check's fix as Site Health shows it, or a listing's steps.
            Empty on other work.
          items:
            type: string
          title: Checklist
          type: array
        citation_count:
          default: 0
          description: Distinct engine and prompt citation pairs before the list cap.
          title: Citation Count
          type: integer
        citations:
          description: >-
            Distinct engine and stable prompt citation pairs in the publication
            measurement window, capped at five.
          items:
            $ref: '#/components/schemas/FirstCitation'
          title: Citations
          type: array
        completed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Completed At
        content_piece:
          anyOf:
            - $ref: '#/components/schemas/V1ActionPiece'
            - type: 'null'
        correspondence:
          anyOf:
            - $ref: '#/components/schemas/V1Correspondence'
            - type: 'null'
          description: >-
            The emails of a task with a source and whose move it is; null on
            work that writes no email.
        created_at:
          format: date-time
          title: Created At
          type: string
        credit_cost:
          title: Credit Cost
          type: integer
        credits_spent:
          description: Content credits charged to this work and not refunded.
          title: Credits Spent
          type: integer
        current_draft_version:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The draft version this action shows; null without a draft, or when
            the newest one was written for another route.
          title: Current Draft Version
        current_step:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Step
        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 waits on, in a line.
          title: Demand
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
        dismissal_reason:
          anyOf:
            - enum:
                - not_now
                - too_much_work
                - not_relevant
                - already_done
              type: string
            - type: 'null'
          description: >-
            Why a member put the work away, while it stays put away. `not_now`
            defers it four weeks. `too_much_work`, `not_relevant` and
            `already_done` dismiss it, and `not_relevant` also stops Heralded
            suggesting that play for that target again. Null when no reason was
            given and once the work is restored.
          title: Dismissal Reason
        dispatchable:
          title: Dispatchable
          type: boolean
        done_when:
          anyOf:
            - type: string
            - type: 'null'
          description: When the work is done.
          title: Done When
        draft_in_flight:
          anyOf:
            - enum:
                - drafting
                - redrafting
              type: string
            - type: 'null'
          title: Draft In Flight
        drafts:
          items:
            $ref: '#/components/schemas/V1ActionDraft'
          title: Drafts
          type: array
        ending:
          anyOf:
            - $ref: '#/components/schemas/EndingResponse'
            - type: 'null'
          description: >-
            How the task ended, such as No reply, Stopped or Not relevant, and
            when; null while it is open. `outcome` keeps its meaning.
        evidence:
          anyOf:
            - $ref: '#/components/schemas/TaskEvidence'
            - type: 'null'
          description: Linked prompts and rendered answer counts from the latest report.
        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.
        fixed_pages:
          description: >-
            Previously affected pages checked as passing by a later Website
            read.
          items:
            type: string
          title: Fixed Pages
          type: array
        focus:
          anyOf:
            - $ref: '#/components/schemas/FocusTag'
            - type: 'null'
          description: >-
            The starred topic or competitor the work serves, or outside your
            focus.
        gain:
          anyOf:
            - $ref: '#/components/schemas/GainResponse'
            - type: 'null'
          description: >-
            The expected gain: its band (high, medium or low, null on work you
            asked for) and what the work aims at.
        gate:
          anyOf:
            - enum:
                - approval
                - review
              type: string
            - type: 'null'
          title: Gate
        grounds:
          anyOf:
            - $ref: '#/components/schemas/GroundsResponse'
            - type: 'null'
          description: >-
            What the work rests on: its kind, its likely cause, the dated
            evidence, the prompt or keyword results it targets and, for best
            practice, the publisher guidance. Null on work filed before actions
            carried their grounds.
        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 work: you, Heralded or a third party; null when nobody
            holds it.
          title: Holder
        id:
          format: uuid
          title: Id
          type: string
        impact_scale:
          anyOf:
            - type: string
            - type: 'null'
          title: Impact Scale
        insight_links:
          description: Every scan that created or reprioritised this action, oldest first.
          items:
            $ref: '#/components/schemas/V1InsightLink'
          title: Insight Links
          type: array
        job:
          $ref: '#/components/schemas/JobResponse'
        kind:
          title: Kind
          type: string
        kind_tag:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A tag on the kind of work, such as Sponsored; null on work that has
            none.
          title: Kind Tag
        looks_resolved_evidence:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: The last observed finding when the work appears resolved.
          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
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        not_seen_since_run:
          anyOf:
            - type: integer
            - type: 'null'
          description: First read that stopped seeing this suggestion; null when seen.
          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'
          title: Outcome
        page:
          anyOf:
            - $ref: '#/components/schemas/ActionSection'
            - type: 'null'
          description: The requested section page and continuation.
        pages:
          description: Affected page URLs, separate from the instructions in `checklist`.
          items:
            type: string
          title: Pages
          type: array
        pages_remaining:
          anyOf:
            - type: integer
            - type: 'null'
          description: Affected pages still requiring a fix before paging.
          title: Pages Remaining
        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
        piece_preview:
          anyOf:
            - $ref: '#/components/schemas/V1ActionPiecePreview'
            - type: 'null'
          description: >-
            Compact piece state without its document or images; present on
            preview reads.
        placed_position:
          anyOf:
            - type: integer
            - type: 'null'
          description: Position in the brand's proposed order; null when Heralded ranks it.
          title: Placed Position
        platform:
          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'
          title: Primary Verb
        prompt_movement:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Movement
        recipient:
          anyOf:
            - $ref: '#/components/schemas/V1ArtifactRecipient'
            - type: 'null'
          description: >-
            Who an outreach task's email is addressed to and where its address
            was found; null on other work.
        results:
          $ref: '#/components/schemas/ActionResults'
          description: >-
            Grouped observations, citation headline, connection offer and
            measured outcome for delivered work.
        return_group:
          anyOf:
            - enum:
                - new
                - your_input
                - dispatched
                - scheduled
                - waiting
                - settled
                - withdrawn
              type: string
            - type: 'null'
          title: Return Group
        route:
          title: Route
          type: string
        scheduled_for:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          title: Scheduled For
        secondary_verbs:
          items:
            enum:
              - dispatch
              - take
              - done
              - defer
              - dismiss
              - confirm
              - reject
              - restore
              - block
              - unblock
              - reopen
            type: string
          title: Secondary Verbs
          type: array
        section_totals:
          additionalProperties:
            type: integer
          description: Rows in each compact section before paging.
          title: Section Totals
          type: object
        segment:
          title: Segment
          type: string
        settled_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Settled At
        setup_link:
          anyOf:
            - $ref: '#/components/schemas/SetupLink'
            - type: 'null'
        stage:
          description: 'The work''s stage: observe, decide, do or verify.'
          enum:
            - observe
            - decide
            - do
            - verify
          title: Stage
          type: string
        started_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The action's first start by Heralded; null on dismissed work.
          title: Started At
        state:
          enum:
            - new
            - accepted
            - in_progress
            - blocked
            - looks_resolved
            - done
            - verified_no_move
            - deferred
            - dismissed
            - withdrawn
          title: State
          type: string
        steps:
          items:
            $ref: '#/components/schemas/V1ActionJobStage'
          title: Steps
          type: array
        target_entity:
          title: Target Entity
          type: string
        targets:
          description: Questions and searches on the requested page.
          items:
            $ref: '#/components/schemas/V1ActionTarget'
          title: Targets
          type: array
        thread:
          items:
            $ref: '#/components/schemas/V1ActionStep'
          title: Thread
          type: array
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        tracking:
          description: What Heralded tracks once the work is live.
          items:
            enum:
              - live
              - crawled
              - ranked
              - search_console
              - cited
              - moved
            type: string
          title: Tracking
          type: array
        trail:
          description: >-
            What happened since the work was delivered: one entry per signal in
            `tracking`, then the `measured` result. A site fix's measured result
            is its `live` entry. Empty until the work is delivered.
          items:
            $ref: '#/components/schemas/TrailEntry'
          title: Trail
          type: array
        updated_at:
          format: date-time
          title: Updated At
          type: string
        verified_impact_pts:
          anyOf:
            - type: number
            - type: 'null'
          title: Verified Impact Pts
        viewer:
          anyOf:
            - $ref: '#/components/schemas/ActionViewerResponse'
            - type: 'null'
          description: >-
            The kit, redraft allowance and activity names visible to this
            caller.
        wait:
          anyOf:
            - $ref: '#/components/schemas/WaitResponse'
            - type: 'null'
          description: >-
            What the task waits for, on whom, until when and who acts then; 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'
          title: Write Language
        write_language_locked:
          default: false
          title: Write Language Locked
          type: boolean
        write_language_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Write Language Source
      required:
        - meta
        - waiting_since
        - route
        - demand
        - first_citation
        - citation_count
        - write_language
        - write_language_source
        - write_language_locked
        - placed_position
        - not_seen_since_run
        - evidence
        - note
        - id
        - title
        - detail
        - kind
        - member
        - started_at
        - delivered_at
        - paid_off_at
        - preview
        - group
        - scheduled_for
        - holder
        - stage
        - outcome
        - grounds
        - done_when
        - tracking
        - gain
        - focus
        - kind_tag
        - ending
        - wait
        - created_at
        - completed_at
        - state
        - target_entity
        - updated_at
        - impact_scale
        - expected_impact_pts
        - verified_impact_pts
        - primary_verb
        - secondary_verbs
        - job
        - credit_cost
        - credits_spent
        - dispatchable
        - platform
        - gate
        - setup_link
        - return_group
        - draft_in_flight
        - piece_preview
        - asset
        - targets
        - pages_remaining
        - looks_resolved_evidence
        - citations
        - results
        - brand_id
        - segment
        - settled_at
        - prompt_movement
        - blocked_owner
        - check_again_on
        - dismissal_reason
        - assignee
        - steps
        - current_step
        - thread
        - drafts
        - current_draft_version
        - recipient
        - correspondence
        - application
        - content_piece
        - insight_links
        - checklist
        - pages
        - fixed_pages
        - trail
      title: V1ActionDetail
      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
    V1ActionApplication:
      properties:
        applied_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Applied At
        approved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Approved At
        desired_value:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          title: Desired Value
          type: object
        effect:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            What applying does to the current value: `overwrite`, `remove` or
            `send` ask the member to confirm first.
          title: Effect
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Reason
        fix_kind:
          title: Fix Kind
          type: string
        id:
          format: uuid
          title: Id
          type: string
        planned_against_value:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/JsonValue'
              type: object
            - type: 'null'
          description: The site's value when the change was planned.
          title: Planned Against Value
        previous_value:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/JsonValue'
              type: object
            - type: 'null'
          title: Previous Value
        provider:
          title: Provider
          type: string
        scheduled_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When an operation that waits for its moment, such as an email, is
            due.
          title: Scheduled At
        state:
          title: State
          type: string
        verified_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Verified At
      required:
        - id
        - state
        - provider
        - fix_kind
        - desired_value
        - planned_against_value
        - effect
        - previous_value
        - failure_reason
        - approved_at
        - scheduled_at
        - applied_at
        - verified_at
      title: V1ActionApplication
      type: object
    V1Asset:
      properties:
        action_id:
          description: The work item that owns this asset.
          format: uuid
          title: Action Id
          type: string
        id:
          description: The current asset identifier.
          format: uuid
          title: Id
          type: string
        kind:
          description: The stored asset family.
          enum:
            - piece
            - draft
            - change
            - kit
          title: Kind
          type: string
        opening:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The first 400 characters of settled text, null before text is
            available.
          title: Opening
        owner:
          anyOf:
            - $ref: '#/components/schemas/AssigneeResponse'
            - type: 'null'
          description: The current eligible owner, null when unassigned or unavailable.
        state:
          anyOf:
            - enum:
                - drafting
                - review
                - approved
                - live
                - stopped
                - failed
              type: string
            - enum:
                - ready
                - verifying
              type: string
          description: The lifecycle group used by the state filter.
          title: State
        title:
          description: The piece title or the owning work title.
          title: Title
          type: string
        type:
          description: The format or artifact type used by the type filter.
          title: Type
          type: string
        updated_at:
          description: When this asset was last updated.
          format: date-time
          title: Updated At
          type: string
        version:
          anyOf:
            - type: integer
            - type: 'null'
          description: The current settled version, null for an unversioned change.
          title: Version
      required:
        - id
        - action_id
        - kind
        - type
        - title
        - version
        - state
        - owner
        - updated_at
        - opening
      title: V1Asset
      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
    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
    V1ActionPiece:
      properties:
        citation_count:
          default: 0
          description: >-
            Distinct engine and stable prompt citation pairs in the publication
            measurement window, before the list cap.
          title: Citation Count
          type: integer
        citations:
          description: >-
            Distinct engine and stable prompt citation pairs in the publication
            measurement window, capped at five.
          items:
            $ref: '#/components/schemas/FirstCitation'
          title: Citations
          type: array
        constraints:
          anyOf:
            - $ref: '#/components/schemas/PieceConstraints'
            - type: 'null'
          description: >-
            What the order asked of the piece: the length in words, the links
            and the date it is needed by, such as an agreed outreach option's
            requirements. Null where the order asked nothing.
        destination_hosts:
          description: >-
            Publication hosts. Defaults to the brand's owned sites, including
            older pieces.
          items:
            type: string
          title: Destination Hosts
          type: array
        draft_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Draft Content
        draft_origin:
          anyOf:
            - type: string
            - type: 'null'
          title: Draft Origin
        draft_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Draft Version
        fields:
          description: The current settled draft's format fields, in the format's order.
          items:
            $ref: '#/components/schemas/V1ActionPieceField'
          title: Fields
          type: array
        first_citation:
          anyOf:
            - $ref: '#/components/schemas/FirstCitation'
            - type: 'null'
          description: First qualifying citation after publication; null while uncited.
        format:
          title: Format
          type: string
        has_brief:
          default: false
          deprecated: true
          description: Whether a retained brief exists. False for new writer pieces.
          title: Has Brief
          type: boolean
        id:
          format: uuid
          title: Id
          type: string
        images:
          $ref: '#/components/schemas/ImageSlots'
          description: >-
            Featured image, generation results and social preview, without
            signed URLs.
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
        published_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Published Url
        report:
          anyOf:
            - $ref: '#/components/schemas/WriterReport'
            - type: 'null'
          description: >-
            Writer questions, sources and checked references; null when
            unavailable.
        stage:
          description: Studio stage projected from the operation and Heralded's gates.
          title: Stage
          type: string
          x-extensible-enum:
            - ordering
            - researching_and_writing
            - applying_comments
            - your_review
            - approved
            - publishing
            - published
            - stopped
            - failed
            - paused
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: The piece title.
          title: Title
        words:
          anyOf:
            - type: integer
            - type: 'null'
          description: Words of prose in the current version; null before a draft.
          title: Words
      required:
        - destination_hosts
        - constraints
        - words
        - report
        - images
        - first_citation
        - citations
        - citation_count
        - id
        - title
        - has_brief
        - stage
        - format
        - language
        - draft_version
        - draft_content
        - fields
        - draft_origin
        - published_url
      title: V1ActionPiece
      type: object
    V1Correspondence:
      description: The emails of a task with a source and whose move it is.
      properties:
        approved:
          additionalProperties:
            type: integer
          description: >-
            The emails approved to go and the draft version approved, by email.
            An email that arrives or an edit voids them.
          title: Approved
          type: object
        article:
          anyOf:
            - $ref: '#/components/schemas/V1CorrespondenceArticle'
            - type: 'null'
          description: >-
            The article the agreement needs, once a member agreed and chose who
            writes it; null otherwise.
        asks_member:
          default: false
          description: >-
            They agreed to co-marketing that only a member can say is live: the
            task completes on a member's word.
          title: Asks Member
          type: boolean
        awaiting:
          anyOf:
            - $ref: '#/components/schemas/V1Commitment'
            - type: 'null'
          description: What they agreed to do, which the task waits for.
        away_until:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When they said they are back.
          title: Away Until
        closed:
          anyOf:
            - enum:
                - no_reply
                - no_reply_recorded
                - declined
                - opted_out
                - stopped
              type: string
            - type: 'null'
          description: How the task closed, while it stays closed.
          title: Closed
        closed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the task closed, while it stays closed.
          title: Closed At
        due_on:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When that wait falls due.
          title: Due On
        email_count:
          description: All emails on the task.
          title: Email Count
          type: integer
        emails:
          description: The emails, oldest first.
          items:
            $ref: '#/components/schemas/V1Email'
          title: Emails
          type: array
        gaps:
          description: What the email due next still needs from a member before it can go.
          items:
            type: string
          title: Gaps
          type: array
        goal:
          default: named
          description: >-
            What the task is for: to be named on the source, to have a claim
            corrected, or to agree co-marketing.
          enum:
            - named
            - correction
            - co_marketing
          title: Goal
          type: string
        mailbox:
          anyOf:
            - $ref: '#/components/schemas/V1Mailbox'
            - type: 'null'
          description: >-
            The mailbox of this task's sender, with its scheduled send; null
            where they go from the member's own mail.
        next_email:
          anyOf:
            - type: string
              x-extensible-enum:
                - first
                - answer
                - reminder_1
                - reminder_2
                - article
            - type: 'null'
          description: >-
            The email of the brand's that goes next: the first email, an answer
            to theirs, a reminder, or the agreed article; null when none is due.
            Read an unknown value as another email of the brand's.
          title: Next Email
        offers:
          description: >-
            The terms on the table, every version oldest first; empty when
            withheld.
          items:
            $ref: '#/components/schemas/V1Offer'
          title: Offers
          type: array
        our_deadline:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The date they need something still owed from the brand by.
          title: Our Deadline
        published_check:
          anyOf:
            - type: string
              x-extensible-enum:
                - pending
                - named
                - not_named
                - unreadable
            - type: 'null'
          description: >-
            What Heralded's read of `published_url` found: still to read, the
            page names the brand, it is live without naming the brand, or it
            could not be read.
          title: Published Check
        published_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Where they said the work is live, on their own site.
          title: Published Url
        reminders:
          description: >-
            The reminders approving the email due next approves with it, the
            newest draft of each; empty when none follows it or the text is
            withheld.
          items:
            $ref: '#/components/schemas/V1ActionDraft'
          title: Reminders
          type: array
        reopened_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When an email arrived after the task closed unanswered and opened
            it.
          title: Reopened At
        requests:
          description: >-
            What they asked of the brand that is still open; empty when
            withheld.
          items:
            $ref: '#/components/schemas/V1ReadRequest'
          title: Requests
          type: array
        sender:
          $ref: '#/components/schemas/V1ConversationSender'
          description: The conversation's pinned sender and current pause reason.
        state:
          anyOf:
            - $ref: '#/components/schemas/ConversationState'
            - type: 'null'
          description: >-
            Where the conversation stands, served so no client works it out:
            whose move it is, the email due next and who sends it, the wait, the
            step, the recipient and what each side owes. Work rows read the same
            whose move, wait and step.
        taken_over_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When a member took the emails over; Heralded writes no more of them.
          title: Taken Over At
        thread_subject:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The subject a reminder, an answer or the agreed article goes under,
            in the thread the first email started; null for the first email,
            whose subject opens its draft.
          title: Thread Subject
        turn:
          description: >-
            `theirs` while the task waits on the source, `yours` while a
            member's move, `closed` once the task settled.
          enum:
            - yours
            - theirs
            - closed
          title: Turn
          type: string
        waiting_for:
          anyOf:
            - enum:
                - reminder
                - quiet
                - asked
                - their_date
                - queued
              type: string
            - type: 'null'
          description: >-
            What the task waits for: the next reminder's date, the quiet days
            after the last one, an answer to whether they replied, a date the
            source gave, or another task to the same contact closing.
          title: Waiting For
        waiting_since:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the brand's last email went.
          title: Waiting Since
      required:
        - sender
        - turn
        - waiting_for
        - due_on
        - next_email
        - approved
        - waiting_since
        - taken_over_at
        - closed
        - closed_at
        - reopened_at
        - gaps
        - reminders
        - thread_subject
        - emails
        - email_count
        - goal
        - offers
        - requests
        - awaiting
        - away_until
        - published_url
        - our_deadline
        - asks_member
        - article
        - published_check
        - state
        - mailbox
      title: V1Correspondence
      type: object
    V1ActionDraft:
      properties:
        angle:
          anyOf:
            - type: string
            - type: 'null'
          title: Angle
        answers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            For an answer to their email: the ids of the conversation's
            obligations it answers (`correspondence.state.obligations`), which
            sending its text settles. Null on every other draft, and on an
            answer drafted before answers were recorded.
          title: Answers
        body:
          title: Body
          type: string
        created_at:
          format: date-time
          title: Created At
          type: string
        email:
          anyOf:
            - enum:
                - reminder_1
                - reminder_2
              type: string
            - type: 'null'
          description: >-
            Which email of a task with a source this version is for: null for
            the turn's leading email (the first email, or an answer), and for
            every draft of work that writes no email.
          title: Email
        english_body:
          anyOf:
            - type: string
            - type: 'null'
          description: Stored English text of an outreach email draft, where translated.
          title: English Body
        from_address:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The chosen From address. An empty string selects your own mail; null
            keeps an existing draft's sending path. Changing it creates a
            version requiring approval.
          title: From Address
        gaps:
          description: >-
            What the draft still needs from a member before it can go, each gap
            in the order it stands. Filling one saves that gap alone.
          items:
            $ref: '#/components/schemas/DraftGapResponse'
          readOnly: true
          title: Gaps
          type: array
        id:
          format: uuid
          title: Id
          type: string
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
        revision_closed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Revision Closed At
        revision_requested_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Revision Requested At
        turn:
          default: 0
          description: >-
            The turn of a task's emails this version is for: 0 for the first
            email and its reminders, otherwise an answer to an email of theirs
            and its reminders.
          title: Turn
          type: integer
        type:
          title: Type
          type: string
        version:
          title: Version
          type: integer
        written_by:
          description: 'Who wrote this version: Heralded''s draft, or a member''s edit.'
          enum:
            - heralded
            - member
          readOnly: true
          title: Written By
          type: string
      required:
        - language
        - email
        - turn
        - id
        - version
        - type
        - body
        - from_address
        - english_body
        - answers
        - angle
        - revision_requested_at
        - revision_closed_at
        - created_at
        - written_by
        - gaps
      title: V1ActionDraft
      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
    TaskEvidence:
      properties:
        answers_link:
          anyOf:
            - $ref: '#/components/schemas/AnswersLink'
            - type: 'null'
        prompts:
          items:
            $ref: '#/components/schemas/TaskPromptEvidence'
          title: Prompts
          type: array
      required:
        - prompts
        - answers_link
      title: TaskEvidence
      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
    V1InsightLink:
      description: One scan that created or reprioritised the action.
      properties:
        change:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/JsonValue'
              type: object
            - type: 'null'
          description: The priority inputs this scan changed, each `{from, to}`.
          title: Change
        created_at:
          format: date-time
          title: Created At
          type: string
        kind:
          title: Kind
          type: string
        run_number:
          title: Run Number
          type: integer
        statement:
          anyOf:
            - type: string
            - type: 'null'
          description: The finding's statement; null once its evidence is deleted.
          title: Statement
      required:
        - kind
        - run_number
        - change
        - statement
        - created_at
      title: V1InsightLink
      type: object
    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
    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
    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
    ActionSection:
      properties:
        key:
          description: The section being paged.
          title: Key
          type: string
        limit:
          description: Maximum rows in this section page.
          title: Limit
          type: integer
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: Next page of this section, with the same section and limit.
          title: Next Cursor
        offset:
          description: Rows skipped in this section.
          title: Offset
          type: integer
        total:
          description: All rows in this section before paging.
          title: Total
          type: integer
      required:
        - next_cursor
        - key
        - total
        - offset
        - limit
      title: ActionSection
      type: object
    V1ActionPiecePreview:
      properties:
        draft_version:
          anyOf:
            - type: integer
            - type: 'null'
          description: The settled draft version, null before a draft exists.
          title: Draft Version
        format:
          description: The writing format.
          title: Format
          type: string
        has_brief:
          deprecated: true
          description: Whether a retained brief exists. False for new writer pieces.
          title: Has Brief
          type: boolean
        id:
          description: The current-generation piece identifier.
          format: uuid
          title: Id
          type: string
        language:
          anyOf:
            - type: string
            - type: 'null'
          description: The piece language.
          title: Language
        published_url:
          anyOf:
            - type: string
            - type: 'null'
          description: The recorded live URL, null before publication.
          title: Published Url
        stage:
          description: The current detailed piece stage.
          title: Stage
          type: string
          x-extensible-enum:
            - ordering
            - researching_and_writing
            - applying_comments
            - your_review
            - approved
            - publishing
            - published
            - stopped
            - failed
            - paused
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: The piece title.
          title: Title
      required:
        - id
        - title
        - has_brief
        - stage
        - format
        - language
        - draft_version
        - published_url
      title: V1ActionPiecePreview
      type: object
    V1ArtifactRecipient:
      description: |-
        Who an outreach task is addressed to: a person, or the site's team where
        `person` is null, and which cited page named them; and the address its
        email goes to, whom it reaches and where it was found.
      properties:
        address:
          anyOf:
            - type: string
            - type: 'null'
          description: The address the email goes to; null while none is known.
          title: Address
        address_found_in:
          anyOf:
            - enum:
                - author_page
                - contact_page
                - commercial_page
                - home_page
                - member
              type: string
            - type: 'null'
          description: >-
            Where the address was found: the cited page that names its author,
            the site's contact, commercial or home page, or a member.
          title: Address Found In
        address_page_url:
          anyOf:
            - type: string
            - type: 'null'
          description: The page the address was read from; null for a member's.
          title: Address Page Url
        candidate:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: A found contact awaiting your choice after a refusal.
          title: Candidate
        discovery:
          anyOf:
            - $ref: '#/components/schemas/RecipientDiscovery'
            - type: 'null'
          description: >-
            The source lookup behind this recipient; null before classification
            or while a newer source read awaits this task's refresh.
        found_in:
          anyOf:
            - enum:
                - json_ld
                - author_meta
                - byline
              type: string
            - type: 'null'
          title: Found In
        generic:
          default: false
          description: >-
            Whether the address is a mailbox the site keeps for a role, such as
            editor@ or info@, rather than a person's.
          title: Generic
          type: boolean
        page_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Url
        person:
          anyOf:
            - type: string
            - type: 'null'
          title: Person
        role:
          anyOf:
            - enum:
                - editorial
                - commercial
              type: string
            - type: 'null'
          description: >-
            Whether the address reaches the site's editors or its commercial
            team; null when its role is unknown or a member gave the address.
          title: Role
        site_name:
          title: Site Name
          type: string
      required:
        - discovery
        - candidate
        - person
        - site_name
        - found_in
        - page_url
        - address
        - role
        - address_found_in
        - address_page_url
        - generic
      title: V1ArtifactRecipient
      type: object
    ActionResults:
      properties:
        citation_count:
          default: 0
          description: >-
            Distinct engine and stable prompt pairs in the publication
            measurement window, before the five-row cap.
          title: Citation Count
          type: integer
        citations:
          description: >-
            First observation per engine and stable prompt, capped at five
            within the measurement window.
          items:
            $ref: '#/components/schemas/FirstCitation'
          title: Citations
          type: array
        connect:
          anyOf:
            - $ref: '#/components/schemas/ConnectResults'
            - type: 'null'
          description: >-
            Neutral connection offer for the missing sources, or null when none
            are missing.
        engine_count:
          default: 0
          description: >-
            Distinct engines citing this publication within its measurement
            window, before the list cap.
          title: Engine Count
          type: integer
        first_citation:
          anyOf:
            - $ref: '#/components/schemas/FirstCitation'
            - type: 'null'
          description: >-
            First qualifying citation after this publication; null until one is
            observed.
        headline:
          anyOf:
            - $ref: '#/components/schemas/ResultEntry'
            - type: 'null'
          description: >-
            Verified gain, otherwise the first citation; absent until either
            exists.
        measured:
          anyOf:
            - $ref: '#/components/schemas/ResultEntry'
            - type: 'null'
          description: >-
            Measured outcome or its due date, separate from citation
            observations.
        prompt_count:
          default: 0
          description: >-
            Distinct stable prompts citing this publication within its
            measurement window, across engines and before the list cap.
          title: Prompt Count
          type: integer
        results:
          description: >-
            Confirmed citation, publication, crawler, ranking and Search Console
            observations.
          items:
            $ref: '#/components/schemas/ResultEntry'
          title: Results
          type: array
        status_label:
          default: Delivered
          description: >-
            Paying off requires verification of the targeted answer metric
            against untouched questions; otherwise a tracked citation takes
            precedence over delivery.
          enum:
            - Delivered
            - Cited
            - Paying off
          title: Status Label
          type: string
        steps:
          description: >-
            One step per declared tracking signal, in play order, then the
            measured answer outcome. Includes pending, unchanged, unavailable
            and inconclusive states. A site fix's verification is its live step.
          items:
            $ref: '#/components/schemas/ResultStep'
          title: Steps
          type: array
        targeted_prompts:
          description: >-
            New brand mentions on prompts this work targets; no claim that the
            page was cited.
          items:
            $ref: '#/components/schemas/ResultEntry'
          title: Targeted Prompts
          type: array
        warnings:
          description: Signals whose reads failed, excluding missing connections.
          items:
            $ref: '#/components/schemas/ResultEntry'
          title: Warnings
          type: array
        watching:
          description: Pending and unchanged signals with something to watch.
          items:
            $ref: '#/components/schemas/ResultEntry'
          title: Watching
          type: array
      required:
        - first_citation
        - citations
        - citation_count
        - engine_count
        - prompt_count
        - status_label
        - steps
        - headline
        - results
        - targeted_prompts
        - watching
        - warnings
        - connect
        - measured
      title: ActionResults
      type: object
    SetupLink:
      properties:
        href:
          title: Href
          type: string
        label:
          title: Label
          type: string
      required:
        - label
        - href
      title: SetupLink
      type: object
    V1ActionJobStage:
      properties:
        doer:
          enum:
            - heralded
            - member
            - watch
          title: Doer
          type: string
        done_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Done At
        event_count:
          default: 0
          description: This step's entries before paging; zero on a section read.
          title: Event Count
          type: integer
        events:
          description: >-
            What happened at this step, oldest first, identical events as one
            entry. A full read carries every one and a compact read the latest
            five; a section read carries none, and `section=activity` with
            `step` pages them. An event of a kind no step owns shows under the
            step last finished when it happened, or the first step.
          items:
            $ref: '#/components/schemas/V1ActionStep'
          title: Events
          type: array
        key:
          title: Key
          type: string
        label:
          title: Label
          type: string
        lane:
          default: main
          description: >-
            main, or article for the article an outreach agreement needs, whose
            steps run beside the emails.
          enum:
            - main
            - article
          title: Lane
          type: string
        line:
          title: Line
          type: string
        status:
          default: ahead
          description: >-
            Where the step stands: done, now, ahead, or ended, the step 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
        - events
        - event_count
      title: V1ActionJobStage
      type: object
    V1ActionTarget:
      properties:
        answer_count:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Measured answers to this question, null for searches or unmeasured
            targets.
          title: Answer Count
        answers_link:
          anyOf:
            - $ref: '#/components/schemas/AnswersLink'
            - type: 'null'
          description: >-
            Answers supporting this target, null when no measured answers are
            available.
        engine:
          anyOf:
            - type: string
            - type: 'null'
          description: The engine addressed, null when the target spans engines.
          title: Engine
        kind:
          description: Whether the target is an AI question or Google search.
          enum:
            - prompt
            - keyword
          title: Kind
          type: string
        named_count:
          anyOf:
            - type: integer
            - type: 'null'
          description: Answers naming the brand; null for searches or unmeasured questions.
          title: Named Count
        text:
          description: The resolved question or search text.
          title: Text
          type: string
        uid:
          description: The stable question or keyword identifier.
          format: uuid
          title: Uid
          type: string
      required:
        - kind
        - uid
        - text
        - engine
        - named_count
        - answer_count
        - answers_link
      title: V1ActionTarget
      type: object
    V1ActionStep:
      properties:
        actor:
          title: Actor
          type: string
        detail:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/JsonValue'
              type: object
            - type: 'null'
          title: Detail
        id:
          format: uuid
          title: Id
          type: string
        kind:
          title: Kind
          type: string
        line:
          default: ''
          description: >-
            The event in words for this reader: who did it and what they did,
            "You" where the reader took the step, dates in words and no version
            numbers. `summary` is the same line for no reader in particular,
            worded when it is read.
          title: Line
          type: string
        occurred_at:
          format: date-time
          title: Occurred At
          type: string
        repeat_count:
          default: 1
          description: Identical visible activity events represented by this entry.
          minimum: 1
          title: Repeat Count
          type: integer
        retry_after_failure:
          default: false
          description: This unblock requested a retry after a failed draft.
          title: Retry After Failure
          type: boolean
        summary:
          title: Summary
          type: string
        tone:
          anyOf:
            - const: failure
              type: string
            - type: 'null'
          description: failure for an event that failed; null otherwise.
          title: Tone
      required:
        - id
        - kind
        - actor
        - summary
        - detail
        - occurred_at
        - repeat_count
        - retry_after_failure
        - line
        - tone
      title: V1ActionStep
      type: object
    TrailEntry:
      description: One line of what happened since the work was delivered.
      properties:
        at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When it was observed or last looked at; for a pending measured
            result, when the result is due, where that is known.
          title: At
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: Why it could not be checked; null otherwise.
          title: Reason
        signal:
          anyOf:
            - enum:
                - live
                - crawled
                - ranked
                - search_console
                - cited
                - moved
              type: string
            - const: measured
              type: string
          description: >-
            What was watched. `measured` is the credited verification, the
            strongest entry; a site fix's verification is its `live` entry.
          title: Signal
        state:
          description: >-
            `good`: it happened. `no_change`: Heralded looked and it has not
            happened yet. `couldnt_check`: Heralded could not look, for
            `reason`. `pending`: nothing to say yet.
          enum:
            - good
            - no_change
            - couldnt_check
            - pending
          title: State
          type: string
        summary:
          anyOf:
            - type: string
            - type: 'null'
          description: The line as Heralded wrote it; null while pending.
          title: Summary
      required:
        - signal
        - state
        - summary
        - reason
        - at
      title: TrailEntry
      type: object
    ActionViewerResponse:
      properties:
        approvable:
          default: true
          description: Whether this viewer may approve from the task's stored sender.
          title: Approvable
          type: boolean
        assigned_to_you:
          default: false
          description: Whether the work is assigned to this caller.
          title: Assigned To You
          type: boolean
        kit:
          anyOf:
            - $ref: '#/components/schemas/SiteKitResponse'
            - type: 'null'
          description: The current fix kit, null without a kit.
        picks_up_work:
          default: false
          description: Whether this work area starts suggestions automatically.
          title: Picks Up Work
          type: boolean
        redrafts_left:
          description: Free short-draft revisions remaining.
          title: Redrafts Left
          type: integer
        sender_choices:
          anyOf:
            - $ref: '#/components/schemas/SenderChoices'
            - type: 'null'
          description: >-
            Viewer-specific sender groups for an email task; null for other work
            or redacted text.
        sender_gap:
          anyOf:
            - type: string
            - type: 'null'
          description: The choice still owed when neither a sender nor a suggestion exists.
          title: Sender Gap
        sender_owner_account_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The stored mailbox owner's account ID, to assign the task to them;
            null without an owner.
          title: Sender Owner Account Id
        sender_owner_first_name:
          anyOf:
            - type: string
            - type: 'null'
          description: The stored mailbox owner's first name, when available.
          title: Sender Owner First Name
        sender_suggestion:
          anyOf:
            - $ref: '#/components/schemas/SenderSuggestion'
            - type: 'null'
          description: >-
            The viewer's sole personal mailbox, otherwise the sole shared
            mailbox; null without a unique suggestion.
        thread:
          description: Viewer-specific names for the returned activity events.
          items:
            $ref: '#/components/schemas/ThreadStepViewer'
          title: Thread
          type: array
      required:
        - sender_choices
        - sender_suggestion
        - approvable
        - sender_owner_first_name
        - sender_owner_account_id
        - sender_gap
        - picks_up_work
        - kit
        - redrafts_left
        - assigned_to_you
        - thread
      title: ActionViewerResponse
      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
    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
    JsonValue: {}
    PieceConstraints:
      description: |-
        What the order asks of the piece: its length in words, the links it
        carries and the date it is needed by.
      properties:
        deadline:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When the piece is needed by.
          title: Deadline
        links:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          description: How many links the piece carries, where asked.
          title: Links
        words:
          anyOf:
            - $ref: '#/components/schemas/WordBand'
            - type: 'null'
          description: The length asked for, in words.
      required:
        - words
        - links
        - deadline
      title: PieceConstraints
      type: object
    V1ActionPieceField:
      properties:
        label:
          description: The field's label, as supplied by the writing format.
          title: Label
          type: string
        name:
          description: The format field's name, such as `title` or `meta_description`.
          title: Name
          type: string
        value:
          description: The field's text on the current settled draft.
          title: Value
          type: string
      required:
        - name
        - label
        - value
      title: V1ActionPieceField
      type: object
    ImageSlots:
      properties:
        featured:
          $ref: '#/components/schemas/FeaturedRead'
          description: >-
            Optional featured image and its generation allowance and earlier
            results.
        social:
          $ref: '#/components/schemas/SocialRead'
          description: Sharing image and branded-card style.
      required:
        - featured
        - social
      title: ImageSlots
      type: object
    WriterReport:
      properties:
        questions:
          description: Questions the brand can answer; none blocks approval.
          items:
            type: string
          title: Questions
          type: array
        references:
          description: Passages checked against the recorded sources.
          items:
            $ref: '#/components/schemas/RecordedReference'
          title: References
          type: array
        resolved_questions:
          description: Questions answered or dismissed by a member on this piece.
          items:
            type: string
          title: Resolved Questions
          type: array
        sources:
          description: Material the writer recorded for this piece.
          items:
            $ref: '#/components/schemas/RecordedSource'
          title: Sources
          type: array
      required:
        - resolved_questions
        - questions
        - sources
        - references
      title: WriterReport
      type: object
    V1CorrespondenceArticle:
      description: The article an agreement on a task with a source needs (#9353).
      properties:
        action_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The content action the article is when Heralded writes it: its piece
            is this task's asset, and it is never a row of its own in Work.
          title: Action Id
        by:
          description: 'Who writes it: Heralded, as a piece in Studio, or the brand itself.'
          enum:
            - heralded
            - member
          title: By
          type: string
        credits:
          default: 0
          description: The content credits ordering it took.
          title: Credits
          type: integer
        deadline:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When they need it by.
          title: Deadline
        piece_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The article's piece, once ordered from the writer.
          title: Piece Id
        requirements:
          anyOf:
            - type: string
            - type: 'null'
          description: What they asked of the article, in one line.
          title: Requirements
        revision_requested_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When they asked for changes to the article they were sent, while the
            revision has not gone.
          title: Revision Requested At
        sent_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When it last went.
          title: Sent At
        sent_version:
          anyOf:
            - type: integer
            - type: 'null'
          description: The piece version that last went to them.
          title: Sent Version
        stage:
          description: >-
            Where it stands: the brand writing it, Heralded writing it or a
            revision of it, waiting for review, approved to go, failed, or sent
            with no change owed. Read an unknown value as writing.
          enum:
            - member
            - writing
            - review
            - approved
            - failed
            - sent
          title: Stage
          type: string
      required:
        - by
        - stage
        - action_id
        - piece_id
        - credits
        - requirements
        - deadline
        - sent_version
        - sent_at
        - revision_requested_at
      title: V1CorrespondenceArticle
      type: object
    V1Commitment:
      properties:
        by:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When, where they gave a date.
          title: By
        what:
          description: What they said they will do.
          title: What
          type: string
      required:
        - what
        - by
      title: V1Commitment
      type: object
    V1Email:
      description: One email on a task with a source, either way (#9344).
      properties:
        arrived_by:
          description: >-
            How Heralded learned of it: `marked_sent` when a member marked the
            approved email sent, `pasted` for a reply a member pasted, `noted`
            for a reply a member said came without its text, `member_reply` for
            an email a member wrote from their own mail, `bcc` for a sent copy,
            `forwarded` for a forwarded reply, and `mailbox` for an email sent
            or synced through the brand's connected mailbox. Read an unknown
            value as another way it arrived.
          title: Arrived By
          type: string
          x-extensible-enum:
            - marked_sent
            - pasted
            - noted
            - member_reply
            - bcc
            - forwarded
            - mailbox
        attachments:
          description: Attachment names and byte sizes; empty when withheld.
          items:
            $ref: '#/components/schemas/V1MailAttachment'
          title: Attachments
          type: array
        body_format:
          default: plain
          description: >-
            How to render the text: markdown for Heralded-composed mail, plain
            for other mail.
          enum:
            - plain
            - markdown
          title: Body Format
          type: string
        direction:
          description: '`out` for an email of the brand''s, `in` for one from the source.'
          enum:
            - in
            - out
          title: Direction
          type: string
        email:
          anyOf:
            - type: string
              x-extensible-enum:
                - first
                - answer
                - reminder_1
                - reminder_2
                - article
            - type: 'null'
          description: >-
            Which approved email of the brand's this was: the first email, an
            answer to theirs, a reminder after either, or the agreed article;
            null for any other. Read an unknown value as another email of the
            brand's.
          title: Email
        english_text:
          anyOf:
            - type: string
            - type: 'null'
          description: Stored English text, where translated; null when withheld.
          title: English Text
        id:
          description: The email's identifier.
          format: uuid
          title: Id
          type: string
        language:
          anyOf:
            - type: string
            - type: 'null'
          description: Its language code; null when unknown or withheld.
          title: Language
        new_text:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The sender's new words without quoted mail; null when the split is
            uncertain or the text is withheld.
          title: New Text
        occurred_at:
          description: When it was sent or received.
          format: date-time
          title: Occurred At
          type: string
        party_name:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The served contact name, mail display name or address; null when
            withheld.
          title: Party Name
        reading:
          anyOf:
            - $ref: '#/components/schemas/V1EmailReading'
            - type: 'null'
          description: >-
            What Heralded read in an email of theirs; null for an email of the
            brand's, one that came without its text, and when withheld.
        recipients:
          description: Who it went to; empty when withheld.
          items:
            $ref: '#/components/schemas/V1EmailParty'
          title: Recipients
          type: array
        sender:
          anyOf:
            - $ref: '#/components/schemas/V1EmailParty'
            - type: 'null'
          description: Who it is from; null when withheld.
        subject:
          anyOf:
            - type: string
            - type: 'null'
          description: Its subject; null when unknown or withheld.
          title: Subject
        text:
          anyOf:
            - type: string
            - type: 'null'
          description: Its text; null when unknown or withheld.
          title: Text
      required:
        - id
        - direction
        - arrived_by
        - occurred_at
        - email
        - subject
        - text
        - new_text
        - body_format
        - party_name
        - language
        - english_text
        - sender
        - recipients
        - attachments
        - reading
      title: V1Email
      type: object
    V1Mailbox:
      description: The mailbox of this task's sender, with its scheduled send (#9349).
      properties:
        address:
          anyOf:
            - type: string
            - type: 'null'
          description: The connected mailbox account; null once none is connected.
          title: Address
        connected:
          description: >-
            Whether the mailbox can send. Without it nothing goes; a member who
            can start work may send from their own mail instead.
          title: Connected
          type: boolean
        daily_limit:
          description: >-
            The emails the mailbox sends a day, across every brand sending from
            it. An approved email past it waits for the next working day
            (`send.daily_limit`).
          title: Daily Limit
          type: integer
        default_from:
          anyOf:
            - type: string
            - type: 'null'
          description: The address the conversation's emails go from (`sender.address`).
          title: Default From
        reconnect_by:
          description: Who can connect the mailbox again, while it is not connected.
          items:
            type: string
          title: Reconnect By
          type: array
        send:
          anyOf:
            - $ref: '#/components/schemas/V1EmailSend'
            - type: 'null'
          description: The email on its way, while one is.
        sends_as:
          description: >-
            The addresses a task may send from through the mailbox: its own and
            each alias that passed the From test. The daily sending limit is
            shared by all addresses of the account.
          items:
            type: string
          title: Sends As
          type: array
        time_zone:
          anyOf:
            - type: string
            - type: 'null'
          description: The mailbox's IANA time zone, whose working hours its emails go in.
          title: Time Zone
      required:
        - address
        - time_zone
        - connected
        - sends_as
        - default_from
        - reconnect_by
        - daily_limit
        - send
      title: V1Mailbox
      type: object
    V1Offer:
      description: |-
        One version of the terms on the table of a task with a source
        (#9345). Private to the brand.
      properties:
        article_credits:
          default: 0
          description: >-
            The content credits Heralded writing the article costs; 0 when
            agreeing needs no article.
          title: Article Credits
          type: integer
        conditions:
          anyOf:
            - type: string
            - type: 'null'
          description: Any other condition they set.
          title: Conditions
        created_at:
          description: When the version was made.
          format: date-time
          title: Created At
          type: string
        decided_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When it was answered.
          title: Decided At
        decision:
          anyOf:
            - $ref: '#/components/schemas/V1OfferDecision'
            - type: 'null'
          description: The member's answer to this version.
        email_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The email the terms came in; null for a member's version.
          title: Email Id
        labelling:
          anyOf:
            - type: string
            - type: 'null'
          description: What they said about labelling the placement.
          title: Labelling
        made_by:
          description: >-
            `reading` for terms read from their email, `member` for terms a
            member corrected or added.
          enum:
            - reading
            - member
          title: Made By
          type: string
        needs_article:
          default: false
          description: >-
            Whether agreeing needs an article from the brand, which they asked
            for: agreeing then says who writes it, Heralded for
            `article_credits` content credits or the brand itself for none.
          title: Needs Article
          type: boolean
        options:
          description: Each priced option.
          items:
            $ref: '#/components/schemas/V1OfferOption'
          title: Options
          type: array
        payment_due:
          anyOf:
            - type: string
              x-extensible-enum:
                - upfront
                - after_publication
            - type: 'null'
          description: >-
            When they are paid for the offer: `upfront`, or `after_publication`
            once it is live; null where they did not say.
          title: Payment Due
        state:
          description: >-
            `open` until a member answers it; `superseded` once a newer version
            replaced it unanswered.
          enum:
            - open
            - agreed
            - countered
            - asked_free
            - declined
            - superseded
          title: State
          type: string
        told_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: 'When that email went: the time the decision reached them.'
          title: Told At
        told_email_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The email of ours that told them the decision; null while it is not
            told, or was never decided.
          title: Told Email Id
        version:
          description: 1 for the first terms on the task, one higher per change.
          title: Version
          type: integer
        ways:
          description: >-
            The ways to answer it while it is open: agree to an option, offer
            less, ask for the free option, or decline.
          items:
            enum:
              - agree
              - offer_less
              - ask_free
              - decline
            type: string
          title: Ways
          type: array
      required:
        - version
        - state
        - options
        - labelling
        - conditions
        - payment_due
        - made_by
        - email_id
        - decision
        - decided_at
        - told_email_id
        - told_at
        - created_at
        - ways
        - needs_article
        - article_credits
      title: V1Offer
      type: object
    V1ReadRequest:
      properties:
        deadline:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When they need it by, if they said.
          title: Deadline
        kind:
          description: What they ask the brand for.
          enum:
            - question
            - description
            - logo
            - link
            - test_account
            - billing_details
            - article
            - rates
            - other
          title: Kind
          type: string
        text:
          description: The request in one short line.
          title: Text
          type: string
      required:
        - kind
        - text
        - deadline
      title: V1ReadRequest
      type: object
    V1ConversationSender:
      description: |-
        Who the conversation's emails go from (#9629): the sender pinned on it,
        or with none the mailbox the brand would use, who sends, and why a
        pinned sender can no longer send.
      properties:
        account_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The mailbox connection the emails go from, pinned or suggested,
            retained after deletion; null for own mail and while no mailbox
            would send.
          title: Account Id
        address:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The address the emails go from, pinned or suggested, redacted for
            staff; null for own mail until a copy from it names the address, and
            while nothing would send.
          title: Address
        paused_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          deprecated: true
          description: >-
            Always null: the pause is derived when read, not dated. Kept until
            the web stops reading it.
          title: Paused At
        paused_reason:
          anyOf:
            - enum:
                - made_personal
                - owner_left
                - disconnected
                - reconnect_required
                - alias_removed
                - owner_cannot_send
              type: string
            - type: 'null'
          description: >-
            Why the pinned sender can no longer send for the conversation; null
            while it can.
          title: Paused Reason
        pinned:
          default: false
          description: >-
            Whether a member, a continuation or a sent email chose the sender;
            false for the brand's suggested mailbox and while there is none.
          title: Pinned
          type: boolean
        state:
          default: unset
          description: >-
            Where the conversation's emails go from once an email went or a
            member continued it from a sender: a mailbox, the member's own mail,
            or a mailbox no longer available. `unset` before then, while From is
            a member's choice or a suggestion.
          enum:
            - unset
            - mailbox
            - own_mail
            - unavailable
          title: State
          type: string
        who_sends:
          default: member
          description: >-
            Who sends the emails: Heralded from the mailbox, or a member from
            their own mail.
          enum:
            - heralded
            - member
          title: Who Sends
          type: string
      required:
        - state
        - account_id
        - address
        - pinned
        - who_sends
        - paused_reason
        - paused_at
      title: V1ConversationSender
      type: object
    ConversationState:
      description: |-
        Where the conversation stands, served so no surface works it out
        (#9465).
      properties:
        missed:
          anyOf:
            - enum:
                - their_date
                - our_deadline
                - follow_up
              type: string
            - type: 'null'
          description: >-
            A date that passed with a follow-up drafted for a member to review
            or skip: the date they gave, the date they needed something by, or a
            follow-up of the brand's that fell due.
          title: Missed
        next_email:
          anyOf:
            - $ref: '#/components/schemas/NextEmail'
            - type: 'null'
          description: The email of the brand's due next; null when none is.
        obligations:
          description: >-
            What each side owes: every open obligation and the most recently
            settled.
          items:
            $ref: '#/components/schemas/ConversationObligation'
          title: Obligations
          type: array
        recipient:
          anyOf:
            - $ref: '#/components/schemas/ConversationRecipient'
            - type: 'null'
          description: Who the emails go to; null when withheld.
        step:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The key of the stage of the task's Steps it stands at; null once it
            settled or stopped.
          title: Step
        wait:
          anyOf:
            - $ref: '#/components/schemas/WaitResponse'
            - type: 'null'
          description: >-
            What the task waits for, the same object a row's `wait` is; null
            while it waits on nobody.
        whose_move:
          anyOf:
            - enum:
                - us
                - them
              type: string
            - type: 'null'
          description: >-
            `us` while the brand owes an email or something it agreed to, `them`
            while the task waits on the source; null once closed, or while it
            waits behind another task to the same contact.
          title: Whose Move
      required:
        - whose_move
        - next_email
        - wait
        - step
        - missed
        - recipient
        - obligations
      title: ConversationState
      type: object
    DraftGapResponse:
      description: Something only a member can say, marked in a draft where it goes.
      properties:
        index:
          description: Its place among the draft's gaps, from 0, in the order they stand.
          title: Index
          type: integer
        kind:
          description: >-
            What filling it takes: `answer` an answer the member writes, as its
            own paragraph; `fact` a fact they supply in its sentence; `choose`
            their choice on an offer; `signature` the brand's email signature;
            `opt_out` the sentence for opting out.
          enum:
            - answer
            - fact
            - choose
            - signature
            - opt_out
          title: Kind
          type: string
        label:
          description: What it asks for, as the draft states it.
          title: Label
          type: string
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The obligation the gap answers (`correspondence.state.obligations`);
            null for a gap no request asked for.
          title: Request Id
        target:
          description: >-
            Where filling it is saved. draft: the draft's own text; signature:
            the brand's email signature, which also fills it in every first
            email still missing it.
          enum:
            - draft
            - signature
          title: Target
          type: string
      required:
        - index
        - label
        - kind
        - request_id
        - target
      title: DraftGapResponse
      type: object
    AnswersLink:
      properties:
        href:
          title: Href
          type: string
      required:
        - href
      title: AnswersLink
      type: object
    TaskPromptEvidence:
      properties:
        answer_count:
          description: Answers supporting this prompt or evidence row.
          title: Answer Count
          type: integer
        answers_link:
          $ref: '#/components/schemas/AnswersLink'
        named_count:
          description: Answers in the selection that name the brand.
          title: Named Count
          type: integer
        prompt_uid:
          format: uuid
          title: Prompt Uid
          type: string
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
      required:
        - prompt_uid
        - text
        - named_count
        - answer_count
        - answers_link
      title: TaskPromptEvidence
      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
    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
    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
    RecipientDiscovery:
      properties:
        message:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A customer-facing reason for a missing address; null when an address
            was found.
          title: Message
        outcome:
          description: >-
            Whether the source was unreadable, searched without an address, or
            yielded an address.
          enum:
            - unreadable
            - searched_none
            - found
          title: Outcome
          type: string
      required:
        - outcome
        - message
      title: RecipientDiscovery
      type: object
    ConnectResults:
      properties:
        href:
          description: Brand connections settings path.
          title: Href
          type: string
        label:
          default: Connect
          description: Connection control label.
          title: Label
          type: string
        sources:
          description: Only the missing sources offered for connection.
          items:
            enum:
              - search_console
              - crawler_visits
            type: string
          title: Sources
          type: array
        state:
          const: not_connected
          default: not_connected
          description: The sources are absent, rather than a read failing.
          title: State
          type: string
        summary:
          description: Offer naming the missing sources.
          title: Summary
          type: string
        tone:
          const: neutral
          default: neutral
          description: Missing connections are neutral.
          title: Tone
          type: string
      required:
        - state
        - tone
        - sources
        - summary
        - label
        - href
      title: ConnectResults
      type: object
    ResultEntry:
      properties:
        answer_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Answer to open when this signal has recoverable answer evidence.
          title: Answer Id
        at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Observation time, or measurement due date while pending.
          title: At
        citation:
          anyOf:
            - $ref: '#/components/schemas/FirstCitation'
            - type: 'null'
          description: Qualifying citation evidence; null for other signals.
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Engine display name when the signal concerns one engine.
          title: Display Name
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Prompt text when the signal concerns an answer.
          title: Prompt
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: Reason a signal could not be checked; null otherwise.
          title: Reason
        signal:
          anyOf:
            - enum:
                - live
                - crawled
                - ranked
                - search_console
                - cited
                - moved
              type: string
            - const: measured
              type: string
          description: Signal this observation concerns.
          title: Signal
        state:
          anyOf:
            - enum:
                - good
                - no_change
                - couldnt_check
                - pending
              type: string
            - const: not_connected
              type: string
          description: >-
            Success, unchanged or pending signal, failed read, or missing
            connection.
          title: State
        summary:
          anyOf:
            - type: string
            - type: 'null'
          description: Observed result; null while pending.
          title: Summary
        tone:
          description: Success, neutral watching, or warning for a failed read.
          enum:
            - good
            - neutral
            - warning
          title: Tone
          type: string
      required:
        - signal
        - tone
        - summary
        - reason
        - at
        - answer_id
        - display_name
        - prompt
        - citation
        - state
      title: ResultEntry
      type: object
    ResultStep:
      properties:
        answer_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Answer to open when this signal has recoverable answer evidence.
          title: Answer Id
        at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Observation time, or measurement due date while pending.
          title: At
        citation:
          anyOf:
            - $ref: '#/components/schemas/FirstCitation'
            - type: 'null'
          description: Qualifying citation evidence; null for other signals.
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Engine display name when the signal concerns one engine.
          title: Display Name
        label:
          description: Result step or measured outcome in customer-facing words.
          title: Label
          type: string
        metric:
          anyOf:
            - enum:
                - mentioned
                - recommended
              type: string
            - type: 'null'
          description: Verified answer metric; null for observations and other outcomes.
          title: Metric
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Prompt text when the signal concerns an answer.
          title: Prompt
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: Reason a signal could not be checked; null otherwise.
          title: Reason
        signal:
          anyOf:
            - enum:
                - live
                - crawled
                - ranked
                - search_console
                - cited
                - moved
              type: string
            - const: measured
              type: string
          description: Signal this observation concerns.
          title: Signal
        state:
          anyOf:
            - enum:
                - good
                - no_change
                - couldnt_check
                - pending
              type: string
            - enum:
                - not_connected
                - no_effect
                - fell
                - inconclusive
              type: string
          description: >-
            Observed, pending, unchanged, unavailable, or measured outcome
            state.
          title: State
        summary:
          anyOf:
            - type: string
            - type: 'null'
          description: Observed result; null while pending.
          title: Summary
        tone:
          description: Success, neutral watching, or warning for a failed read.
          enum:
            - good
            - neutral
            - warning
          title: Tone
          type: string
      required:
        - signal
        - tone
        - summary
        - reason
        - at
        - answer_id
        - display_name
        - prompt
        - citation
        - label
        - state
        - metric
      title: ResultStep
      type: object
    SiteKitResponse:
      properties:
        body:
          description: The fix kit text.
          title: Body
          type: string
        filename:
          anyOf:
            - type: string
            - type: 'null'
          description: The download filename, null for a pasted snippet.
          title: Filename
        placement:
          description: Where the member puts the kit.
          title: Placement
          type: string
      required:
        - body
        - placement
        - filename
      title: SiteKitResponse
      type: object
    SenderChoices:
      properties:
        own_mail:
          default: true
          description: Whether the viewer may choose to send through their own mail.
          title: Own Mail
          type: boolean
        shared:
          description: Shared mailboxes this viewer may use.
          items:
            $ref: '#/components/schemas/SenderChoiceMailbox'
          title: Shared
          type: array
        yours:
          description: The viewer's usable personal mailboxes.
          items:
            $ref: '#/components/schemas/SenderChoiceMailbox'
          title: Yours
          type: array
      required:
        - yours
        - shared
        - own_mail
      title: SenderChoices
      type: object
    SenderSuggestion:
      properties:
        account_id:
          description: >-
            The suggested connection instance ID, without replacing a stored
            choice.
          format: uuid
          title: Account Id
          type: string
        address:
          description: The suggested instance's default From address.
          title: Address
          type: string
      required:
        - account_id
        - address
      title: SenderSuggestion
      type: object
    ThreadStepViewer:
      properties:
        actor_name:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The name this caller may see, null for a hidden or unavailable
            account.
          title: Actor Name
        by_viewer:
          description: Whether this caller performed the event.
          title: By Viewer
          type: boolean
        id:
          description: The visible activity event.
          format: uuid
          title: Id
          type: string
      required:
        - id
        - actor_name
        - by_viewer
      title: ThreadStepViewer
      type: object
    WordBand:
      properties:
        max:
          description: Most words, inclusive.
          minimum: 1
          title: Max
          type: integer
        min:
          description: Fewest words, inclusive.
          minimum: 1
          title: Min
          type: integer
        stated:
          anyOf:
            - enum:
                - about
                - range
              type: string
            - type: 'null'
          description: >-
            Whether they stated one approximate count or an explicit range; null
            on older bands.
          title: Stated
      required:
        - min
        - max
        - stated
      title: WordBand
      type: object
    FeaturedRead:
      properties:
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: The latest generation description, else the suggested subject.
          title: Description
        earlier_results:
          description: This piece's generation requests, newest first, including failures.
          items:
            $ref: '#/components/schemas/ImageResult'
          title: Earlier Results
          type: array
        failure_code:
          anyOf:
            - type: string
            - type: 'null'
          description: The selected request's machine-readable failure reason.
          title: Failure Code
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: The selected request's refusal or failure explanation.
          title: Failure Reason
        generation_state:
          anyOf:
            - type: string
            - type: 'null'
          description: A generation still running or waiting after any image selection.
          title: Generation State
        generations_left:
          description: >-
            Remaining out of ten, less this piece's successful and AI-refused
            generations.
          title: Generations Left
          type: integer
        image:
          anyOf:
            - $ref: '#/components/schemas/ImageFile'
            - type: 'null'
          description: The selected featured image, if set.
        shows_real_person:
          default: false
          description: >-
            Whether removing the selected upload withdraws consent and deletes
            its file.
          title: Shows Real Person
          type: boolean
        state:
          description: The selected featured request's state, or empty.
          title: State
          type: string
        style:
          default: photo
          description: The latest generation's style preset.
          enum:
            - photo
            - illustration
            - three_d
            - isometric
            - line_art
            - abstract
          title: Style
          type: string
        suggested_description:
          anyOf:
            - type: string
            - type: 'null'
          description: The first suggested subject, kept unchanged for this piece.
          title: Suggested Description
        suggestion_state:
          default: empty
          description: The one-time description suggestion's state.
          title: Suggestion State
          type: string
      required:
        - state
        - image
        - generations_left
        - earlier_results
        - description
        - style
        - suggestion_state
        - shows_real_person
        - generation_state
        - suggested_description
        - failure_code
        - failure_reason
      title: FeaturedRead
      type: object
    SocialRead:
      properties:
        failure_code:
          anyOf:
            - type: string
            - type: 'null'
          description: The branded render's machine-readable failure reason.
          title: Failure Code
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: The branded render's refusal or failure explanation.
          title: Failure Reason
        image:
          anyOf:
            - $ref: '#/components/schemas/ImageFile'
            - type: 'null'
          description: The social image currently available to download.
        source:
          description: >-
            Sharing source: card by default, or image_only for the plain
            featured image.
          enum:
            - card
            - image_only
            - featured
            - branded
          title: Source
          type: string
        state:
          description: The social image's state, pending until its first card settles.
          title: State
          type: string
        style:
          description: >-
            Effective branded-card style, from the piece override or brand
            default.
          enum:
            - mounted
            - strip
            - band
          title: Style
          type: string
        style_override:
          anyOf:
            - enum:
                - mounted
                - strip
                - band
              type: string
            - type: 'null'
          description: The member's per-piece style, or null to follow the brand default.
          title: Style Override
      required:
        - state
        - source
        - style
        - style_override
        - image
        - failure_code
        - failure_reason
      title: SocialRead
      type: object
    RecordedReference:
      properties:
        quote:
          description: The passage checked by the writer.
          title: Quote
          type: string
        source:
          description: The ref of the source this passage was checked against.
          title: Source
          type: string
        verified:
          description: Whether the source confirmed the passage.
          title: Verified
          type: boolean
      required:
        - source
        - quote
        - verified
      title: RecordedReference
      type: object
    RecordedSource:
      properties:
        first_person:
          default: false
          description: Whether the brand may narrate it as its own.
          title: First Person
          type: boolean
        internal:
          default: false
          description: Whether the material is internal to the brand.
          title: Internal
          type: boolean
        kind:
          description: The kind of material the writer recorded.
          title: Kind
          type: string
        observed_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the material was observed.
          title: Observed At
        ref:
          description: The source reference used by this report's references.
          title: Ref
          type: string
        revision:
          anyOf:
            - type: string
            - type: 'null'
          description: The source revision, when recorded.
          title: Revision
        subject:
          anyOf:
            - type: string
            - type: 'null'
          description: The subject the source supports.
          title: Subject
        support_kind:
          anyOf:
            - type: string
            - type: 'null'
          description: How the source supports the piece.
          title: Support Kind
        text:
          description: The source text retained by the writer.
          title: Text
          type: string
        unavailable_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: Why the material could not be read.
          title: Unavailable Reason
        url:
          anyOf:
            - type: string
            - type: 'null'
          description: The source URL, when available.
          title: Url
      required:
        - kind
        - ref
        - text
      title: RecordedSource
      type: object
    V1MailAttachment:
      properties:
        name:
          description: The attachment's filename. Open it in your own mailbox.
          title: Name
          type: string
        size:
          description: The attachment's size in bytes. Heralded keeps no file bytes.
          title: Size
          type: integer
      required:
        - name
        - size
      title: V1MailAttachment
      type: object
    V1EmailReading:
      description: What Heralded read in an email of theirs (#9345).
      properties:
        agreed:
          default: false
          description: They agreed to what the brand asked.
          title: Agreed
          type: boolean
        answer:
          anyOf:
            - enum:
                - 'yes'
                - 'no'
                - already
                - conditional
                - none
              type: string
            - type: 'null'
          description: >-
            How they answered what the brand asked: agreed, refused, already
            done, agreed on a condition or a price, or did not answer it.
          title: Answer
        asks_payment:
          default: false
          description: They asked to be paid.
          title: Asks Payment
          type: boolean
        automatic:
          default: false
          description: 'An automatic reply, such as an away notice: not a reply.'
          title: Automatic
          type: boolean
        away_until:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When they are back.
          title: Away Until
        commitment:
          anyOf:
            - $ref: '#/components/schemas/V1Commitment'
            - type: 'null'
          description: What they said they will do.
        contact:
          anyOf:
            - $ref: '#/components/schemas/V1EmailParty'
            - type: 'null'
          description: Another person they said to write to.
        opt_out:
          default: false
          description: They asked not to be contacted again.
          title: Opt Out
          type: boolean
        published_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Where they said the brand's mention or piece is live.
          title: Published Url
        requests:
          description: What they asked of the brand.
          items:
            $ref: '#/components/schemas/V1ReadRequest'
          title: Requests
          type: array
        said:
          anyOf:
            - type: string
            - type: 'null'
          description: One sentence of what they said.
          title: Said
        state:
          description: >-
            `pending` while Heralded reads it, `read` once read, `unread` when
            it could not be read: then nothing on the task changed because of
            it.
          enum:
            - pending
            - read
            - unread
          title: State
          type: string
      required:
        - state
        - said
        - answer
        - automatic
        - opt_out
        - agreed
        - asks_payment
        - requests
        - commitment
        - away_until
        - contact
        - published_url
      title: V1EmailReading
      type: object
    V1EmailParty:
      properties:
        address:
          anyOf:
            - type: string
            - type: 'null'
          description: The email address, where known.
          title: Address
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: The name the email carries, if any.
          title: Name
      required:
        - name
        - address
      title: V1EmailParty
      type: object
    V1EmailSend:
      description: An approved email on its way from its conversation's mailbox (#9349).
      properties:
        daily_limit:
          description: >-
            Whether the mailbox's emails for the day were booked, so it goes on
            a later day.
          title: Daily Limit
          type: boolean
        email:
          anyOf:
            - type: string
              x-extensible-enum:
                - first
                - reminder_1
                - reminder_2
                - article
            - type: 'null'
          description: >-
            Which email it carries: the first email or an answer (`first`), a
            follow-up, or the agreed article. A retry of an email that was not
            delivered names the email it sends again. Read an unknown value as
            another email of the brand's.
          title: Email
        from_address:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The address the email goes from, fixed when it was approved: the
            mailbox's own address or one of its aliases. `sender` stays the
            mailbox whose sent mail holds it. Null for an email approved before
            it was recorded.
          title: From Address
        scheduled_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When it goes: a weekday between 09:00 and 17:00 in the mailbox's
            time zone.
          title: Scheduled At
        sender:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The mailbox it leaves, or left, from: the one it was approved
            through, whose sent mail an unconfirmed send is checked in, even
            after the brand's mailboxes changed.
          title: Sender
        state:
          description: >-
            `scheduled` while it waits for its moment and can still be undone,
            `sending` while it goes, `unresolved` when Heralded could not
            confirm it went: a member checks the mailbox's sent mail and settles
            it, and the task waits.
          enum:
            - scheduled
            - sending
            - unresolved
          title: State
          type: string
        version:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The draft version it carries, the one approved; the piece version
            for the article.
          title: Version
      required:
        - state
        - scheduled_at
        - daily_limit
        - sender
        - from_address
        - email
        - version
      title: V1EmailSend
      type: object
    V1OfferDecision:
      properties:
        amount:
          anyOf:
            - type: string
            - type: 'null'
          description: What the brand offered instead.
          title: Amount
        currency:
          anyOf:
            - type: string
            - type: 'null'
          description: The currency of that amount.
          title: Currency
        option:
          anyOf:
            - type: integer
            - type: 'null'
          description: The agreed or countered option's zero-based index.
          title: Option
        option_key:
          anyOf:
            - type: string
            - type: 'null'
          description: The agreed or countered option's key.
          title: Option Key
        way:
          description: How the member answered the offer.
          enum:
            - agree
            - offer_less
            - ask_free
            - decline
          title: Way
          type: string
        writer:
          anyOf:
            - enum:
                - them
                - heralded
                - member
                - none
              type: string
            - type: 'null'
          description: >-
            Who writes the article the agreement needs: `them`, `heralded`,
            `member` (the brand's own team) or `none` where no article is
            needed. Set when the member agrees to an option that carries one;
            null on every other decision.
          title: Writer
      required:
        - way
        - option
        - option_key
        - writer
        - amount
        - currency
      title: V1OfferDecision
      type: object
    V1OfferOption:
      properties:
        amount:
          description: The price, as a decimal string.
          title: Amount
          type: string
        article_credits:
          default: 0
          description: Content credits if Heralded writes this option's article.
          title: Article Credits
          type: integer
        change:
          anyOf:
            - type: string
            - type: 'null'
          description: What changed in the terms to decide on.
          title: Change
        conditions:
          anyOf:
            - type: string
            - type: 'null'
          description: Conditions specific to this option.
          title: Conditions
        currency:
          description: The ISO 4217 currency code.
          title: Currency
          type: string
        deliverable:
          anyOf:
            - $ref: '#/components/schemas/OfferDeliverable'
            - type: 'null'
          description: What this option delivers.
        duration:
          anyOf:
            - type: string
            - type: 'null'
          description: How long it stays live.
          title: Duration
        includes:
          anyOf:
            - type: string
            - type: 'null'
          description: What this option gets the brand.
          title: Includes
        key:
          anyOf:
            - type: string
            - type: 'null'
          description: Stable option identity; null on legacy terms.
          title: Key
        labelling:
          anyOf:
            - type: string
            - type: 'null'
          description: How the placement is labelled.
          title: Labelling
        needs_article:
          default: false
          description: Whether agreeing to this option needs an article choice.
          title: Needs Article
          type: boolean
        payment_due:
          anyOf:
            - type: string
              x-extensible-enum:
                - upfront
                - after_publication
            - type: 'null'
          description: >-
            When this option is paid, only where it differs from the offer's
            `payment_due`; `terms.payment_due` is the one that applies.
          title: Payment Due
        requirements:
          anyOf:
            - $ref: '#/components/schemas/OfferRequirements'
            - type: 'null'
          description: Requirements specific to this option.
        terms:
          $ref: '#/components/schemas/OptionTerms'
          description: >-
            Effective labelling, conditions and requirements, including
            whole-offer terms. The option's other term fields retain their
            stored scope for editing.
        writer:
          anyOf:
            - enum:
                - brand
                - them
                - none
              type: string
            - type: 'null'
          description: >-
            Who supplies the piece; null when uncertain, none when no piece is
            needed.
          title: Writer
      required:
        - amount
        - currency
        - includes
        - duration
        - key
        - deliverable
        - labelling
        - conditions
        - writer
        - requirements
        - payment_due
        - terms
        - change
        - needs_article
        - article_credits
      title: V1OfferOption
      type: object
    NextEmail:
      description: The email of the brand's that goes next.
      properties:
        approved:
          description: Whether a member approved it to go.
          title: Approved
          type: boolean
        at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When Heralded sends it: the time its send is scheduled for, or the
            first working hour of the day it falls due, never before an away
            date they gave. Null when a member sends it or nothing has approved
            it.
          title: At
        email:
          description: >-
            The first email, an answer to theirs, a follow-up, or the agreed
            article. Read an unknown value as another email of the brand's.
          title: Email
          type: string
          x-extensible-enum:
            - first
            - answer
            - reminder_1
            - reminder_2
            - article
        first:
          description: >-
            Whether it opens its own thread: no email of the brand's has reached
            them yet, or it goes to another address than the last one that did.
          title: First
          type: boolean
        gaps:
          default: 0
          description: >-
            The gaps a member still fills before it can go, in it and in the
            follow-ups approved with it, the brand's signature once: filling it
            fills every email.
          title: Gaps
          type: integer
        held:
          anyOf:
            - type: string
              x-extensible-enum:
                - mailbox_disconnected
                - gap_unfilled
                - address_required
                - address_refused
            - type: 'null'
          description: >-
            Why it can't go yet, as approving it now would be refused: the
            brand's mailbox that sends it is disconnected, it or a follow-up
            approved with it has gaps a member must fill, or there is no address
            to send it to. Null when nothing holds it. Read an unknown value as
            held.
          title: Held
        purpose:
          description: >-
            What it is for: `pitch` the first email to a source; `follow_up` a
            reminder in the same thread; `answer` an answer to what they asked;
            `hold` an answer saying the brand comes back on their terms;
            `decision` the brand's decision on their terms; `covering` the note
            the agreed article goes under; `chase` a check on a date that
            passed; `introduction` a first email to a new contact. Read an
            unknown value as another email of the brand's.
          title: Purpose
          type: string
          x-extensible-enum:
            - pitch
            - follow_up
            - answer
            - hold
            - decision
            - covering
            - chase
            - introduction
        sends:
          description: >-
            Who sends it: Heralded from the brand's mailbox, or a member from
            their own mail.
          enum:
            - heralded
            - member
          title: Sends
          type: string
      required:
        - email
        - first
        - approved
        - sends
        - at
        - purpose
        - held
        - gaps
      title: NextEmail
      type: object
    ConversationObligation:
      description: One thing a side owes in the conversation (#9464).
      properties:
        actionable:
          description: >-
            Open with everything it waits on settled: only these are anybody's
            move.
          title: Actionable
          type: boolean
        after:
          description: The obligations that must be settled first.
          items:
            type: string
          title: After
          type: array
        due_on:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When it is due, where known.
          title: Due On
        due_source:
          anyOf:
            - enum:
                - given
                - default
                - ours
              type: string
            - type: 'null'
          description: Where its date came from.
          title: Due Source
        id:
          description: The obligation's identifier.
          title: Id
          type: string
        kind:
          description: What kind of thing it is. Read an unknown value as other.
          title: Kind
          type: string
          x-extensible-enum:
            - answer
            - material
            - article
            - publish
            - place
            - payment
            - call
            - other
        option_key:
          anyOf:
            - type: string
            - type: 'null'
          description: The offer option it holds for; null where it holds for any.
          title: Option Key
        party:
          description: 'Who owes it: the brand, or the source.'
          enum:
            - us
            - them
          title: Party
          type: string
        settled_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When it settled or dropped.
          title: Settled At
        status:
          description: Open, settled, or dropped because it no longer applies.
          enum:
            - open
            - settled
            - dropped
          title: Status
          type: string
        waits_on:
          anyOf:
            - type: string
            - type: 'null'
          description: When an open one that cannot be acted on yet becomes due, in words.
          title: Waits On
        what:
          anyOf:
            - type: string
            - type: 'null'
          description: What is owed, in one line; null when withheld.
          title: What
      required:
        - id
        - party
        - kind
        - what
        - due_on
        - due_source
        - status
        - actionable
        - after
        - waits_on
        - option_key
        - settled_at
      title: ConversationObligation
      type: object
    ConversationRecipient:
      description: Who the task's emails go to.
      properties:
        address:
          anyOf:
            - type: string
            - type: 'null'
          description: The address the next email goes to; null while none is known.
          title: Address
        candidate:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            A found contact awaiting your choice; it changes nothing until
            chosen.
          title: Candidate
        changeable:
          description: >-
            Whether a member may give another address now. A refused address is
            rejected with 409 `address_suppressed`.
          title: Changeable
          type: boolean
        found_in:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Where the address was found: `member` for one a member gave, else
            the kind of page it was read on.
          title: Found In
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: The contact's name, where known.
          title: Name
        page_url:
          anyOf:
            - type: string
            - type: 'null'
          description: The page the address was read on.
          title: Page Url
        proposed:
          anyOf:
            - $ref: '#/components/schemas/ProposedContact'
            - type: 'null'
          description: >-
            Another person a reply named to write to: the next email goes to
            them, and writing to them makes them the recipient. Null where no
            reply named anyone new.
        refused:
          anyOf:
            - $ref: '#/components/schemas/RecipientRefusal'
            - type: 'null'
          description: >-
            The newest address of this conversation the brand may no longer
            write to; null when none was refused.
        written:
          default: false
          description: >-
            Whether an email of ours has gone to the task's current recipient,
            as distinct from `proposed`.
          title: Written
          type: boolean
      required:
        - address
        - name
        - found_in
        - page_url
        - refused
        - candidate
        - changeable
        - proposed
        - written
      title: ConversationRecipient
      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
    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
    SenderChoiceMailbox:
      properties:
        account_id:
          description: The usable connection instance ID.
          format: uuid
          title: Account Id
          type: string
        address:
          description: The mailbox's own address.
          title: Address
          type: string
        addresses:
          description: Verified Send as addresses available on this instance.
          items:
            $ref: '#/components/schemas/SenderChoiceAddress'
          title: Addresses
          type: array
      required:
        - account_id
        - address
        - addresses
      title: SenderChoiceMailbox
      type: object
    ImageResult:
      properties:
        description:
          description: The description requested for this generation.
          title: Description
          type: string
        failure_code:
          anyOf:
            - type: string
            - type: 'null'
          description: Machine-readable failure reason, when refused or failed.
          title: Failure Code
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: The provider's explanation of a refusal or failure.
          title: Failure Reason
        id:
          description: The generation result to select in Studio.
          title: Id
          type: string
        image:
          anyOf:
            - $ref: '#/components/schemas/ImageFile'
            - type: 'null'
          description: The generated file, once successful.
        state:
          description: >-
            Generation state: pending, running, waiting, succeeded, failed or
            cancelled.
          title: State
          type: string
        style:
          description: The member's featured-image style preset.
          enum:
            - photo
            - illustration
            - three_d
            - isometric
            - line_art
            - abstract
          title: Style
          type: string
      required:
        - id
        - state
        - description
        - style
        - image
        - failure_code
        - failure_reason
      title: ImageResult
      type: object
    ImageFile:
      properties:
        ai_generated:
          description: Whether AI generated the image.
          title: Ai Generated
          type: boolean
        asset_id:
          description: The stored file's asset identifier.
          title: Asset Id
          type: string
        height:
          description: Image height in pixels.
          title: Height
          type: integer
        origin:
          description: How this slot's image was made or selected.
          enum:
            - generated
            - uploaded
            - rendered
            - featured
          title: Origin
          type: string
        realistic_person:
          description: Whether the image needs a realistic-person AI disclosure.
          title: Realistic Person
          type: boolean
        size_bytes:
          description: File size in bytes.
          title: Size Bytes
          type: integer
        version_id:
          description: The selected file version; no signed URL is stored.
          title: Version Id
          type: string
        width:
          description: Image width in pixels.
          title: Width
          type: integer
      required:
        - asset_id
        - version_id
        - origin
        - ai_generated
        - realistic_person
        - width
        - height
        - size_bytes
      title: ImageFile
      type: object
    OfferDeliverable:
      additionalProperties: false
      properties:
        description:
          description: >-
            What this option delivers to the brand, as a noun phrase that reads
            inside a sentence, such as a sponsored guest article: it starts
            lowercase unless its first word is a proper noun the email names.
            Keep word counts, link counts and deadlines only in requirements,
            not in this description.
          maxLength: 300
          title: Description
          type: string
        kind:
          description: The type of placement or piece offered.
          enum:
            - listing
            - review
            - article
            - link
            - other
          title: Kind
          type: string
      required:
        - kind
        - description
      title: OfferDeliverable
      type: object
    OfferRequirements:
      additionalProperties: false
      properties:
        deadline:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: >-
            Date they need material from the brand, as YYYY-MM-DD. Never their
            publication date; that belongs only on a publish commitment's by.
          title: Deadline
        links:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          description: Number of links required or allowed.
          title: Links
        topic:
          anyOf:
            - maxLength: 300
              type: string
            - type: 'null'
          description: The requested subject of the piece.
          title: Topic
        words:
          anyOf:
            - $ref: '#/components/schemas/OfferWords'
            - type: 'null'
          description: >-
            Requested word band. A single stated count is normalised to a ±10%
            band when stored; an explicit range keeps its given limits.
        words_asked:
          anyOf:
            - type: string
            - type: 'null'
          description: The stated length, such as "900–1,100 words".
          readOnly: true
          title: Words Asked
      required:
        - words
        - links
        - topic
        - deadline
        - words_asked
      title: OfferRequirements
      type: object
    OptionTerms:
      properties:
        brand_owes:
          anyOf:
            - items:
                $ref: '#/components/schemas/OwedTerm'
              type: array
            - type: 'null'
          description: >-
            What agreeing to the option leaves the brand to do or send, each its
            own item once agreed; null on options read before this was read.
          title: Brand Owes
        conditions:
          anyOf:
            - type: string
            - type: 'null'
          description: Whole-offer and option-specific conditions combined.
          title: Conditions
        labelling:
          anyOf:
            - type: string
            - type: 'null'
          description: Whole-offer and option-specific labelling combined.
          title: Labelling
        payment_due:
          anyOf:
            - enum:
                - upfront
                - after_publication
              type: string
            - type: 'null'
          description: >-
            When the option is paid: `upfront`, or `after_publication` once it
            is live; null where they did not say.
          title: Payment Due
        requirements:
          anyOf:
            - $ref: '#/components/schemas/OfferRequirements'
            - type: 'null'
          description: The selected option's deliverable requirements.
      required:
        - labelling
        - conditions
        - requirements
        - brand_owes
        - payment_due
      title: OptionTerms
      type: object
    ProposedContact:
      description: Another person a reply named to write to.
      properties:
        address:
          description: Their address.
          title: Address
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: Their name, where the reply gave one.
          title: Name
      required:
        - address
        - name
      title: ProposedContact
      type: object
    RecipientRefusal:
      description: An address of the conversation the brand no longer writes to.
      properties:
        address:
          description: The refused address.
          title: Address
          type: string
        message:
          description: The refusal in words, with its date.
          title: Message
          type: string
        'on':
          description: When it was refused.
          format: date
          title: 'On'
          type: string
        reason:
          description: They asked not to be contacted, or the address bounced for good.
          enum:
            - opt_out
            - hard_bounce
          title: Reason
          type: string
      required:
        - address
        - reason
        - 'on'
        - message
      title: RecipientRefusal
      type: object
    SenderChoiceAddress:
      properties:
        address:
          description: A verified sending address of this mailbox.
          title: Address
          type: string
        kind:
          description: Whether this is the mailbox address or a verified alias.
          enum:
            - mailbox
            - alias
          title: Kind
          type: string
      required:
        - address
        - kind
      title: SenderChoiceAddress
      type: object
    OfferWords:
      additionalProperties: false
      properties:
        max:
          description: Maximum word count, inclusive.
          minimum: 1
          title: Max
          type: integer
        min:
          description: Minimum word count, inclusive.
          minimum: 1
          title: Min
          type: integer
        stated:
          anyOf:
            - enum:
                - about
                - range
              type: string
            - type: 'null'
          description: >-
            about for a single stated count, range for two explicit limits. Keep
            the form they stated.
          title: Stated
      required:
        - min
        - max
        - stated
      title: OfferWords
      type: object
    OwedTerm:
      properties:
        kind:
          description: >-
            What it is, as a request of theirs would name it, such as
            test_account. Read an unknown value as other.
          title: Kind
          type: string
        text:
          description: >-
            A short instruction for Your side, such as Send a test account for
            the editor.
          title: Text
          type: string
      required:
        - kind
        - text
      title: OwedTerm
      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.