> ## 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 Weekly Brief

> The issued decisions for this reader, their completion, and new arrivals separately.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/weekly-brief
openapi: 3.1.0
info:
  description: >-
    Access to one organization's brands, as the member who created the API key.
    A read-only key reads; a full-access key also starts, edits and runs that
    member's Snapshots on the organization's Snapshot credits. Each key may make
    120 requests a minute. Separate organization service tokens can start
    Snapshots and Full audits and read service audits. Every error is an RFC
    9457 problem (`application/problem+json`) whose `code` names it.
  summary: Read your brands' AI visibility and run Snapshots in Heralded.
  title: Heralded API
  version: '1'
servers:
  - url: https://api.heralded.ai
security: []
paths:
  /v1/brands/{brand_id}/weekly-brief:
    get:
      tags:
        - v1
      summary: Get Weekly Brief
      description: >-
        The issued decisions for this reader, their completion, and new arrivals
        separately.
      operationId: listWeeklyBrief
      parameters:
        - description: The brand's UUID from listBrands.
          in: path
          name: brand_id
          required: true
          schema:
            description: The brand's UUID from listBrands.
            format: uuid
            title: Brand Id
            type: string
        - description: Maximum rows (100).
          in: query
          name: limit
          required: false
          schema:
            default: 20
            description: Maximum rows (100).
            maximum: 100
            minimum: 1
            title: Limit
            type: integer
        - description: Prior next_cursor; keep filters and limit.
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                type: string
              - type: 'null'
            description: Prior next_cursor; keep filters and limit.
            title: Cursor
        - description: Completed scan id cutoff.
          in: query
          name: as_of
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Completed scan id cutoff.
            title: As Of
        - description: Rows to skip; prefer cursor paging.
          in: query
          name: offset
          required: false
          schema:
            default: 0
            description: Rows to skip; prefer cursor paging.
            minimum: 0
            title: Offset
            type: integer
        - description: Include the viewer's live Today box alongside the issued brief.
          in: query
          name: with_today
          required: false
          schema:
            default: false
            description: Include the viewer's live Today box alongside the issued brief.
            title: With Today
            type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeeklyBrief'
          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:
    WeeklyBrief:
      examples:
        - decisions: []
          done: false
          issued_at: null
          limit: 20
          meta:
            data_as_of: null
            last_attempt_failed: false
            partial: false
            query: {}
            surfaces: {}
            updating: false
          new_since_monday: []
          new_total: 0
          next_cursor: null
          offset: 0
          remaining: 0
          scan_id: null
          today: null
          total: 0
      properties:
        decisions:
          description: A page of the reader's fixed decision set.
          items:
            $ref: '#/components/schemas/Decision'
          title: Decisions
          type: array
        done:
          description: Every decision in the issued set is answered or no longer applies.
          title: Done
          type: boolean
        issued_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When this fixed decision set issued.
          title: Issued At
        limit:
          description: Maximum rows returned from each decision list.
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        new_since_monday:
          description: >-
            A separate page of member turns and suggestions arriving after
            issue.
          items:
            $ref: '#/components/schemas/Decision'
          title: New Since Monday
          type: array
        new_total:
          description: Current decisions that arrived after issue in this reader's scope.
          title: New Total
          type: integer
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          description: Rows skipped in each decision list.
          title: Offset
          type: integer
        remaining:
          description: Unanswered decisions in that fixed set, excluding later arrivals.
          title: Remaining
          type: integer
        scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The report this brief issued with; null before issue.
          title: Scan Id
        today:
          anyOf:
            - $ref: '#/components/schemas/HomeToday'
            - type: 'null'
          description: The viewer's live Today box.
        total:
          description: Issued decisions in this reader's fixed set.
          title: Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - today
        - scan_id
        - issued_at
        - done
        - remaining
        - decisions
        - new_since_monday
        - new_total
      title: WeeklyBrief
      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
    Decision:
      properties:
        action_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Its stored action, null for a job or removed action.
          title: Action Id
        decided:
          description: A decision has been made, or this request no longer applies.
          title: Decided
          type: boolean
        demand:
          description: What the decision asks the reader to do.
          title: Demand
          type: string
        from_last_week:
          description: The same unanswered decision was in the previous brief.
          title: From Last Week
          type: boolean
        href:
          anyOf:
            - type: string
            - type: 'null'
          description: The work link, null if the work was removed.
          title: Href
        id:
          description: This issued decision's stable identity.
          format: uuid
          title: Id
          type: string
        job_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Its recurring job's work-row identity.
          title: Job Id
        kind:
          description: A member turn or suggested work to start.
          enum:
            - needs_you
            - suggestion
          title: Kind
          type: string
        title:
          description: The work's title when the brief issued.
          title: Title
          type: string
      required:
        - id
        - action_id
        - job_id
        - kind
        - title
        - demand
        - href
        - from_last_week
        - decided
      title: Decision
      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
    HomeToday:
      properties:
        date:
          description: Today's date in UTC.
          format: date
          title: Date
          type: string
        heralded_running:
          description: The first three items Heralded is running.
          items:
            $ref: '#/components/schemas/WorkRowResponse'
          title: Heralded Running
          type: array
        in_flight:
          description: Viewer decisions, team decisions and running items combined.
          title: In Flight
          type: integer
        line:
          description: What else is in flight, or where to begin.
          title: Line
          type: string
        running_line:
          anyOf:
            - type: string
            - type: 'null'
          description: What Heralded has in progress; null when idle.
          title: Running Line
        running_more:
          description: Running items beyond those shown.
          title: Running More
          type: integer
        running_total:
          description: Every item Heralded is running, including recurring jobs.
          title: Running Total
          type: integer
        state:
          description: >-
            A: viewer decisions; B: team decisions; C: only Heralded running; D:
            idle.
          enum:
            - A
            - B
            - C
            - D
          title: State
          type: string
        suggestions:
          description: Suggestions in Work order, focus first.
          items:
            $ref: '#/components/schemas/TodaySuggestion'
          title: Suggestions
          type: array
        team_open:
          description: The two oldest team decisions.
          items:
            $ref: '#/components/schemas/TodayTeamDecision'
          title: Team Open
          type: array
        team_total:
          description: Every open decision assigned to someone else.
          title: Team Total
          type: integer
        title:
          description: The heading for the viewer's current state.
          title: Title
          type: string
        viewer_decision_ids:
          description: The displayed viewer decisions in review order.
          items:
            format: uuid
            type: string
          title: Viewer Decision Ids
          type: array
        viewer_decisions:
          description: Up to three viewer decisions.
          items:
            $ref: '#/components/schemas/WorkRowResponse'
          title: Viewer Decisions
          type: array
        viewer_more:
          description: Viewer decisions beyond the three shown.
          title: Viewer More
          type: integer
        viewer_total:
          description: Every decision currently waiting on the viewer.
          title: Viewer Total
          type: integer
      required:
        - state
        - date
        - title
        - line
        - viewer_decisions
        - viewer_decision_ids
        - viewer_total
        - viewer_more
        - team_open
        - team_total
        - heralded_running
        - running_total
        - running_more
        - running_line
        - suggestions
        - in_flight
      title: HomeToday
      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
    DataAsOf:
      properties:
        completed_at:
          format: date-time
          title: Completed At
          type: string
        id:
          format: uuid
          title: Id
          type: string
      required:
        - id
        - completed_at
      title: DataAsOf
      type: object
    JsonValue: {}
    SurfaceFreshness:
      properties:
        as_of:
          anyOf:
            - $ref: '#/components/schemas/SurfaceAsOf'
            - type: 'null'
          description: The result displayed here.
        last_attempt_failed:
          default: false
          description: The newest attempt failed; any displayed result is retained.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed report is partial.
          title: Partial
          type: boolean
        updating:
          default: false
          description: A newer attempt exists whose result is not yet displayed.
          title: Updating
          type: boolean
      required:
        - as_of
        - partial
        - updating
        - last_attempt_failed
      title: SurfaceFreshness
      type: object
    WorkRowResponse:
      description: |-
        One row of work, as the product reads it.

        The projection fields (`group`, `holder`, `stage`, `demand`) come from
        `project_work` and nothing else, so no consumer re-derives them from
        `state`. Severity and confidence are deliberately absent: priority is
        system-owned and neither is ever shown as a field (D12).
      properties:
        assignee:
          anyOf:
            - $ref: '#/components/schemas/AssigneeResponse'
            - type: 'null'
          description: The person accountable for the work.
        blocked_owner:
          anyOf:
            - type: string
            - type: 'null'
          description: Who the action waits on; null when not blocked.
          title: Blocked Owner
        brand_id:
          description: The brand this work belongs to.
          format: uuid
          readOnly: true
          title: Brand Id
          type: string
        check_again_on:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When to check blocked work again.
          title: Check Again On
        citation_count:
          default: 0
          description: Distinct engine and prompt citation pairs before the list cap.
          title: Citation Count
          type: integer
        completed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the action was marked done.
          title: Completed At
        created_at:
          description: When this work was created.
          format: date-time
          title: Created At
          type: string
        credit_cost:
          description: Content credits needed to dispatch this work.
          title: Credit Cost
          type: integer
        credits_spent:
          description: Content credits charged to this work and not refunded.
          title: Credits Spent
          type: integer
        delivered_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When the result went live, was sent or was published. Null on
            dismissed work.
          title: Delivered At
        demand:
          description: What the work is doing or waiting for.
          title: Demand
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          description: The finding behind the work; null when absent.
          title: Detail
        dispatchable:
          description: Whether Heralded can execute this work.
          title: Dispatchable
          type: boolean
        done_when:
          anyOf:
            - type: string
            - type: 'null'
          description: When the work is done; null on Heralded's own work.
          title: Done When
        draft_in_flight:
          anyOf:
            - enum:
                - drafting
                - redrafting
              type: string
            - type: 'null'
          description: Whether a first draft or redraft is being written.
          title: Draft In Flight
        ending:
          anyOf:
            - $ref: '#/components/schemas/EndingResponse'
            - type: 'null'
          description: >-
            How the task ended: its key, its words and when. Null while it is
            open.
        expected_impact_pts:
          anyOf:
            - type: integer
            - type: 'null'
          description: 'Always null: the expected gain is `gain`.'
          title: Expected Impact Pts
        first_citation:
          anyOf:
            - $ref: '#/components/schemas/FirstCitation'
            - type: 'null'
          description: First qualifying citation of the delivered page.
        focus:
          anyOf:
            - $ref: '#/components/schemas/FocusTag'
            - type: 'null'
          description: >-
            The starred topic or competitor the work serves, or outside your
            focus. Null when the brand has no starred topic or competitor, and
            on Heralded's own work.
        gain:
          anyOf:
            - $ref: '#/components/schemas/GainResponse'
            - type: 'null'
          description: >-
            The expected gain: its band and what the work aims at. Null on
            Heralded's own work.
        gate:
          anyOf:
            - enum:
                - approval
                - review
              type: string
            - type: 'null'
          description: The review or approval awaited; null otherwise.
          title: Gate
        grounds:
          anyOf:
            - $ref: '#/components/schemas/GroundsResponse'
            - type: 'null'
          description: >-
            What the work rests on; null on Heralded's own work and on work
            filed before actions carried their grounds.
        group:
          description: The current work group.
          enum:
            - new
            - your_input
            - dispatched
            - scheduled
            - waiting
            - settled
            - withdrawn
          title: Group
          type: string
        holder:
          anyOf:
            - enum:
                - you
                - heralded
                - waiting
              type: string
            - type: 'null'
          description: Who holds the next step; null when nobody does.
          title: Holder
        id:
          description: The action or recurring job id.
          format: uuid
          title: Id
          type: string
        impact_scale:
          anyOf:
            - type: string
            - type: 'null'
          description: The measure this action aims to improve.
          title: Impact Scale
        intent_bucket:
          anyOf:
            - type: string
            - type: 'null'
          description: The targeted prompt intent; null when absent.
          title: Intent Bucket
        issue_type:
          anyOf:
            - $ref: '#/components/schemas/IssueType'
            - enum:
                - daily_read
                - deep_read
                - inventory_crawl
                - detection_sweep
                - search_sweep
              type: string
          description: The kind of action or recurring job.
          title: Issue Type
        job:
          $ref: '#/components/schemas/JobResponse'
          description: The work's steps and available controls.
        kind_tag:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A tag on the kind of work, shown beside its state, such as
            Sponsored. Null on work that has none.
          title: Kind Tag
        looks_resolved_evidence:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Evidence for a resolution awaiting confirmation.
          title: Looks Resolved Evidence
        member:
          anyOf:
            - enum:
                - writer
                - publicist
                - engineer
                - analyst
              type: string
            - type: 'null'
          description: The responsible team member; null for setup and prompt replacements.
          title: Member
        not_seen_since_run:
          anyOf:
            - type: integer
            - type: 'null'
          description: The first report that stopped seeing the finding.
          title: Not Seen Since Run
        note:
          anyOf:
            - $ref: '#/components/schemas/TaskNote'
            - type: 'null'
          description: Task explanation with a live job step.
        outcome:
          anyOf:
            - enum:
                - verified_up
                - no_move
                - not_measured
                - dismissed
              type: string
            - type: 'null'
          description: How settled work ended; null while pending.
          title: Outcome
        paid_off_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When verification credited a positive measured gain. Null on
            dismissed work.
          title: Paid Off At
        placed_position:
          anyOf:
            - type: integer
            - type: 'null'
          description: The member's place in the proposal order.
          title: Placed Position
        platform:
          default: false
          description: Whether this is Heralded's recurring work.
          title: Platform
          type: boolean
        preview:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Up to 400 characters of draft opening, email recipient and subject,
            or planned change while waiting on you.
          title: Preview
        primary_verb:
          anyOf:
            - enum:
                - dispatch
                - take
                - done
                - defer
                - dismiss
                - confirm
                - reject
                - restore
                - block
                - unblock
                - reopen
              type: string
            - const: review
              type: string
            - type: 'null'
          description: The main offered action; null when none is offered.
          title: Primary Verb
        progress:
          anyOf:
            - $ref: '#/components/schemas/WorkProgressResponse'
            - type: 'null'
          description: The running job's progress.
        prompt_movement:
          anyOf:
            - type: string
            - type: 'null'
          description: Whether other work shares the prompt's movement.
          title: Prompt Movement
        repeat:
          anyOf:
            - enum:
                - daily
                - weekly
                - thrice_weekly
              type: string
            - type: 'null'
          description: The recurring job's schedule.
          title: Repeat
        return_group:
          anyOf:
            - enum:
                - new
                - your_input
                - dispatched
                - scheduled
                - waiting
                - settled
                - withdrawn
              type: string
            - type: 'null'
          description: The work group a return action resumes.
          title: Return Group
        route:
          description: The Command Center page this work concerns.
          enum:
            - home
            - actions
            - prompts
            - search
            - market
            - sources
            - content
            - perception
            - audit
          readOnly: true
          title: Route
          type: string
        run_state:
          anyOf:
            - enum:
                - scheduled
                - running
                - done
                - skipped
                - failed
                - stopped
              type: string
            - type: 'null'
          description: The recurring job's current run state.
          title: Run State
        scheduled_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The recurring job's next start.
          title: Scheduled At
        scheduled_for:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The scheduled start date; null when unset.
          title: Scheduled For
        secondary_verbs:
          description: Other offered actions, in menu order.
          items:
            enum:
              - dispatch
              - take
              - done
              - defer
              - dismiss
              - confirm
              - reject
              - restore
              - block
              - unblock
              - reopen
            type: string
          title: Secondary Verbs
          type: array
        segment:
          description: The work's configured segment label.
          title: Segment
          type: string
        settled_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When measurement or the decision settled.
          title: Settled At
        setup_link:
          anyOf:
            - $ref: '#/components/schemas/SetupLink'
            - type: 'null'
          description: Where to complete this setup task.
        stage:
          description: The work's observe, decide, do or verify stage.
          enum:
            - observe
            - decide
            - do
            - verify
          title: Stage
          type: string
        started_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The first time Heralded started this action. Null on dismissed work.
          title: Started At
        state:
          description: The action's lifecycle state.
          enum:
            - new
            - accepted
            - in_progress
            - blocked
            - looks_resolved
            - done
            - verified_no_move
            - deferred
            - dismissed
            - withdrawn
          title: State
          type: string
        target_entity:
          description: The page, prompt, source or check the work targets.
          title: Target Entity
          type: string
        target_type:
          anyOf:
            - type: string
            - type: 'null'
          description: What the target names; null when unknown.
          title: Target Type
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: The act this work proposes or delivers.
          title: Title
        tracked_domain_id:
          deprecated: true
          description: Deprecated alias of brand_id.
          format: uuid
          title: Tracked Domain Id
          type: string
        tracking:
          description: >-
            What Heralded tracks once the work is live: live, crawled, ranked,
            search_console, cited, moved.
          items:
            enum:
              - live
              - crawled
              - ranked
              - search_console
              - cited
              - moved
            type: string
          title: Tracking
          type: array
        updated_at:
          description: When this work last changed.
          format: date-time
          title: Updated At
          type: string
        verified_impact_pts:
          anyOf:
            - type: number
            - type: 'null'
          description: The measured gain credited to the action.
          title: Verified Impact Pts
        wait:
          anyOf:
            - $ref: '#/components/schemas/WaitResponse'
            - type: 'null'
          description: >-
            What the task waits for, on whom and until when. Null while it waits
            on nobody.
        waiting_since:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the current ask began; null outside your_input.
          title: Waiting Since
        write_language:
          anyOf:
            - type: string
            - type: 'null'
          description: The writing language code.
          title: Write Language
        write_language_locked:
          default: false
          description: Whether writing has locked the language.
          title: Write Language Locked
          type: boolean
        write_language_source:
          anyOf:
            - type: string
            - type: 'null'
          description: How the language was chosen.
          title: Write Language Source
      required:
        - id
        - tracked_domain_id
        - target_entity
        - write_language
        - write_language_source
        - write_language_locked
        - target_type
        - issue_type
        - segment
        - title
        - detail
        - state
        - group
        - holder
        - stage
        - demand
        - member
        - waiting_since
        - started_at
        - delivered_at
        - paid_off_at
        - preview
        - outcome
        - gate
        - settled_at
        - impact_scale
        - expected_impact_pts
        - verified_impact_pts
        - prompt_movement
        - blocked_owner
        - check_again_on
        - scheduled_for
        - scheduled_at
        - repeat
        - progress
        - platform
        - run_state
        - assignee
        - intent_bucket
        - looks_resolved_evidence
        - not_seen_since_run
        - placed_position
        - completed_at
        - created_at
        - updated_at
        - primary_verb
        - setup_link
        - secondary_verbs
        - return_group
        - job
        - note
        - credit_cost
        - credits_spent
        - dispatchable
        - draft_in_flight
        - grounds
        - done_when
        - tracking
        - first_citation
        - citation_count
        - gain
        - focus
        - kind_tag
        - ending
        - wait
        - brand_id
        - route
      title: WorkRowResponse
      type: object
    TodaySuggestion:
      properties:
        cost:
          description: Content credits needed to start; zero means free.
          title: Cost
          type: integer
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: The observation the work leads with, null where it rests on none.
          title: Reason
        row:
          $ref: '#/components/schemas/WorkRowResponse'
          description: The suggested work and its existing start controls.
      required:
        - row
        - reason
        - cost
      title: TodaySuggestion
      type: object
    TodayTeamDecision:
      properties:
        age_days:
          description: UTC calendar days since the current ask began.
          title: Age Days
          type: integer
        assignee_name:
          description: The assignee's first name, or their safe display name.
          title: Assignee Name
          type: string
        row:
          $ref: '#/components/schemas/WorkRowResponse'
          description: The open decision's current work row.
      required:
        - row
        - assignee_name
        - age_days
      title: TodayTeamDecision
      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
    AssigneeResponse:
      properties:
        id:
          format: uuid
          title: Id
          type: string
        initials:
          title: Initials
          type: string
        name:
          title: Name
          type: string
      required:
        - id
        - name
        - initials
      title: AssigneeResponse
      type: object
    EndingResponse:
      description: How an ended task ended.
      properties:
        at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When it ended.
          title: At
        key:
          description: >-
            no_reply, no_reply_recorded, declined, opted_out, stopped, not_now,
            too_much_work, not_relevant or already_done.
          title: Key
          type: string
        label:
          description: The ending in words, such as No reply or Not relevant.
          title: Label
          type: string
      required:
        - key
        - label
        - at
      title: EndingResponse
      type: object
    FirstCitation:
      properties:
        answer_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Answer to open; null when no answer id can be recovered.
          title: Answer Id
        cited_at:
          description: When the citing answer was observed, after publication.
          format: date-time
          title: Cited At
          type: string
        display_name:
          description: Current engine name from the engine registry.
          title: Display Name
          type: string
        engine_id:
          description: Engine that cited the published page.
          title: Engine Id
          type: string
        mark_id:
          description: Engine id used to choose its visual mark.
          readOnly: true
          title: Mark Id
          type: string
        prompt:
          description: Prompt wording in the citing answer.
          title: Prompt
          type: string
        prompt_uid:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Stable prompt id; null on older evidence without one.
          title: Prompt Uid
        scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Read that observed this citation; null when not recorded.
          title: Scan Id
      required:
        - engine_id
        - display_name
        - prompt
        - prompt_uid
        - answer_id
        - cited_at
        - scan_id
        - mark_id
      title: FirstCitation
      type: object
    FocusTag:
      description: The focus a piece of work serves.
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          description: The topic id or competitor key; null outside your focus.
          title: Id
        kind:
          description: A starred topic, a starred competitor, or outside your focus.
          enum:
            - topic
            - competitor
            - outside
          title: Kind
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: Its name; null outside your focus.
          title: Name
      required:
        - kind
        - id
        - name
      title: FocusTag
      type: object
    GainResponse:
      description: The gain a piece of work is expected to bring.
      properties:
        aims_at:
          description: What the work aims at.
          title: Aims At
          type: string
        band:
          anyOf:
            - enum:
                - high
                - medium
                - low
              type: string
            - type: 'null'
          description: >-
            How far the work is expected to move what it aims at: high, medium
            or low. Null where Heralded does not estimate it, on work a member
            asked for.
          title: Band
      required:
        - band
        - aims_at
      title: GainResponse
      type: object
    GroundsResponse:
      description: What a piece of work rests on (#6065).
      properties:
        cause:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The leading observation. Null on work a member asked for with no
            finding or evidence behind it.
          title: Cause
        evidence:
          description: >-
            The dated observations the work rests on, besides the one the cause
            states.
          items:
            $ref: '#/components/schemas/Evidence'
          title: Evidence
          type: array
        guidance:
          description: >-
            The publisher guidance a best-practice action rests on, with the
            date Heralded last checked it. Empty on other grounds.
          items:
            $ref: '#/components/schemas/Guidance'
          title: Guidance
          type: array
        kind:
          description: >-
            your_data: diagnosed from the brand's own reads; category_data: what
            is cited and ranked for rivals and the category; best_practice:
            known to work, with the guidance it rests on; you_asked: a member
            asked for it.
          enum:
            - your_data
            - category_data
            - best_practice
            - you_asked
          title: Kind
          type: string
        observed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: The observation stated by the cause, when its date is known.
          title: Observed At
        targets:
          description: The prompt or keyword results this work targets.
          items:
            $ref: '#/components/schemas/Target'
          title: Targets
          type: array
        why:
          anyOf:
            - type: string
            - type: 'null'
          description: Why this evidence calls for this work.
          title: Why
      required:
        - kind
        - cause
        - evidence
        - guidance
      title: GroundsResponse
      type: object
    IssueType:
      enum:
        - modify_content
        - create_content
        - add_keyword
        - pitch_to_source
        - request_correction
        - close_competitor_gap
        - technical_fix
        - setup
      title: IssueType
      type: string
    JobResponse:
      description: |-
        What this row's task is as a job (#2429): every stage, where it stands,
        what happens next and what the button does. Composed per kind by
        `app.actions.jobs.describe_job`; no surface keeps a second table.
      properties:
        control:
          enum:
            - dispatch
            - act
            - take
          title: Control
          type: string
        current:
          anyOf:
            - type: string
            - type: 'null'
          title: Current
        endings:
          description: >-
            The ways you may end the task in its current state, an ending that
            answers its wait first; empty where none is offered.
          items:
            $ref: '#/components/schemas/EndingChoiceResponse'
          title: Endings
          type: array
        failure:
          anyOf:
            - type: string
            - type: 'null'
          description: Why the piece failed; null unless it did.
          title: Failure
        kind:
          title: Kind
          type: string
        next_step:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Step
        runs_steps:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Runs Steps
        stages:
          items:
            $ref: '#/components/schemas/JobStageResponse'
          title: Stages
          type: array
        step:
          anyOf:
            - $ref: '#/components/schemas/JobStepResponse'
            - type: 'null'
        stopped_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Stopped At
      required:
        - kind
        - stages
        - current
        - stopped_at
        - failure
        - next_step
        - control
        - runs_steps
        - step
        - endings
      title: JobResponse
      type: object
    TaskNote:
      properties:
        how_well_know:
          title: How Well Know
          type: string
        short_form:
          title: Short Form
          type: string
        what_i_need_from_you:
          title: What I Need From You
          type: string
        what_ill_do:
          title: What Ill Do
          type: string
        whats_happening:
          title: Whats Happening
          type: string
        why_it_matters:
          anyOf:
            - type: string
            - type: 'null'
          title: Why It Matters
      required:
        - whats_happening
        - why_it_matters
        - what_ill_do
        - what_i_need_from_you
        - how_well_know
        - short_form
      title: TaskNote
      type: object
    WorkProgressResponse:
      description: |-
        How far an executing read has got (#2446): engines answered of the
        engines asked. The words are the row's; the pips are the client's.
      properties:
        done:
          title: Done
          type: integer
        total:
          title: Total
          type: integer
        unit:
          title: Unit
          type: string
      required:
        - done
        - total
        - unit
      title: WorkProgressResponse
      type: object
    SetupLink:
      properties:
        href:
          title: Href
          type: string
        label:
          title: Label
          type: string
      required:
        - label
        - href
      title: SetupLink
      type: object
    WaitResponse:
      description: What the task waits for.
      properties:
        acts:
          description: 'Who acts when the wait is over: heralded or member.'
          enum:
            - heralded
            - member
          title: Acts
          type: string
        due_on:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When the wait is due; null when it has no date.
          title: Due On
        due_source:
          anyOf:
            - enum:
                - given
                - default
                - ours
              type: string
            - type: 'null'
          description: >-
            Where the date came from: given by them, Heralded's default, or our
            schedule; null without a date.
          title: Due Source
        kind:
          description: >-
            answer to an email of ours, agreed on a date they gave, queued
            behind another task to the same contact, asked whether they replied,
            or blocked on a third party you named.
          enum:
            - answer
            - agreed
            - queued
            - asked
            - blocked
          title: Kind
          type: string
        'on':
          description: Who the task waits on.
          title: 'On'
          type: string
        since:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the wait began.
          title: Since
      required:
        - kind
        - 'on'
        - due_on
        - due_source
        - acts
        - since
      title: WaitResponse
      type: object
    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
    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
  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.