---
title: "Update advisor actions (v2)"
method: POST
path: "/api/v1/alpha/advisor-actions/update-v2"
tags: ["alpha"]
---

# Update advisor actions (v2)

`POST /api/v1/alpha/advisor-actions/update-v2`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/alpha/advisor-actions/update-v2`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Change an Advisor action as the caller (the member, the operator viewing as them, or the API key, recorded on each event): its status (open, in progress, completed or dismissed; dismissing needs a reason), a note, or its whole content as a new revision (naming the revision it was edited from; changed since is stale; keeping the subject and expected effect keeps the action's value, changing either unprices it). A status or content revision makes the action the caller's: autotracking stops changing its status, and reviews stop revising, retiring or merging it, until automation is restored; a note alone changes neither. Answers the action now, every event it recorded in order (the status change, a note the change could not carry, the change of control) and its content revision; a retried Idempotency-Key writes nothing and answers the same.

## Headers

- `Point11-Organization` string, uuid
- `Idempotency-Key` string, uuid, required

## Request body

- AlphaAdvisorActionsUpdateV2Request
  - `actionId` string, uuid, required
  - `state` 'acknowledged' | 'in_progress' | 'done' | 'dismissed': acknowledged is Open; done is Completed
  - `dismissalReason` string
  - `note` string
  - `content` object: The action's whole content, written as its next revision
    - `title` string, required: What to do, in a few words
    - `body` string, required: Why: the evidence-backed rationale
    - `action` string, required: What to do, in detail; may be empty
    - `area` 'product' | 'content' | 'distribution' | 'pricing_packaging' | 'compliance_security' | 'sales_enablement' | 'competitive_positioning' | 'customer_success' | 'operations', required
    - `effort` 'low' | 'medium' | 'high', required
    - `subject` AlphaSubject: The sites, locations and campaigns it is about; none when omitted
      - `sites` object[], required
        - `url` string, uri, required
        - `businessProfileId` string, uuid, nullable, required
      - `locations` object[], required
        - `businessProfileId` string, uuid, nullable, required
        - `locationKey` string, nullable, required
        - `label` string, required
        - `address` string, required
        - `url` string, uri, nullable, required
      - `campaigns` object[], required
        - `id` string, uuid, required
        - `product` 'discovery' | 'experience' | 'inspector', required
    - `expectedEffect` object, nullable: What it is expected to move, on a metric an evidence product declares
      - `product` 'discovery' | 'experience' | 'inspector', required
      - `metric` string, required
      - `unit` 'pp' | 'count' | 'ratio' | 'usd', required
      - `horizon` string, required
      - `estimate` number, nullable, required
      - `low` number, nullable, required
      - `high` number, nullable, required
      - `assumptions` string, required
      - `revenueLineIds` string[]
    - `completionCriteria` object[], nullable: How to tell it is done; autotracking writes its own when none are given
      - `id` string, required: A short stable key, e.g. walk_in_hours_clinic_a
      - `requirement` string, required: What must be visible on the public site, in one sentence
      - `scope` string, required: Where it must be visible: which pages, locations, or plans
  - `expectedRevision` integer: With content: the actionRevision it was edited from; a change since refuses as STALE_WRITE

## Response `200`

Success.

- AlphaAdvisorActionsUpdateV2Response
  - `action` object, required: The action as it now stands
    - `id` string, uuid, required
    - `section` 'awaiting_review' | 'listed' | 'set_aside', nullable, required: awaiting_review: new since the published review; listed: on its order; set_aside: set aside by it. Null when the action is off the list (retired, merged, or every live evidence link's campaign has left)
    - `position` integer, nullable, required: Its place in the published review's order; null while awaiting review or off the list
    - `why` string, nullable, required: The published review's one sentence why it is placed so
    - `reviewId` string, uuid, nullable, required: The published review that placed it
    - `state` 'acknowledged' | 'in_progress' | 'done' | 'dismissed', required: acknowledged is Open; done is Completed
    - `status` 'open' | 'completed' | 'dismissed', required
    - `statusControl` 'automatic' | 'manual', required: automatic: autotracking may complete it and a review may revise it; manual: a person or API key set it
    - `disposition` 'active' | 'set_aside' | 'retired' | 'merged', required
    - `mergedIntoId` string, uuid, nullable, required: The action a review merged it into
    - `actionRevision` integer, required: Advances with every change; update.v2's expectedRevision names it
    - `revision` object, required: Its current content revision
      - `id` string, uuid, required
      - `ordinal` integer, required
    - `content` AlphaContent, required
      - `title` string, required
      - `body` string, required
      - `action` string, required
      - `area` 'product' | 'content' | 'distribution' | 'pricing_packaging' | 'compliance_security' | 'sales_enablement' | 'competitive_positioning' | 'customer_success' | 'operations', required
      - `effort` 'low' | 'medium' | 'high', required
      - `subject` object, required
        - `sites` object[], required
          - `url` string, uri, required
          - `businessProfileId` string, uuid, nullable, required
        - `locations` object[], required
          - `businessProfileId` string, uuid, nullable, required
          - `locationKey` string, nullable, required
          - `label` string, required
          - `address` string, required
          - `url` string, uri, nullable, required
        - `campaigns` object[], required
          - `id` string, uuid, required
          - `product` 'discovery' | 'experience' | 'inspector', required
      - `expectedEffect` object, nullable, required
        - `product` 'discovery' | 'experience' | 'inspector', required
        - `metric` string, required
        - `unit` 'pp' | 'count' | 'ratio' | 'usd', required
        - `horizon` string, required
        - `estimate` number, nullable, required
        - `low` number, nullable, required
        - `high` number, nullable, required
        - `assumptions` string, required
        - `revenueLineIds` string[]
      - `completionCriteria` object[], nullable, required
        - `id` string, required: A short stable key, e.g. walk_in_hours_clinic_a
        - `requirement` string, required: What must be visible on the public site, in one sentence
        - `scope` string, required: Where it must be visible: which pages, locations, or plans
    - `valueUsd` number, nullable, required: The opportunity its expected effect stands for a year on the revenue lines it names, where Advisor priced it: on a campaign, a share of those lines' AI-influenced market, not the company's revenue, so it can exceed the brand's own sales; on a site Inspector measures, the brand's own sales on those lines that its mobile speed moves
    - `valueUnpriced` 'no_expected_effect' | 'no_estimate' | 'not_an_increase' | 'unit_unpriced' | 'metric_unpriced' | 'no_campaign' | 'not_measured' | 'no_revenue_economics', nullable, required: Why it has no dollar value, where a review said: no_expected_effect, no_estimate, not_an_increase, unit_unpriced, metric_unpriced (no owner prices its metric), no_campaign, not_measured (nothing measured on its campaign yet to price it), or no_revenue_economics (its campaign's revenue lines have no Revenue Tracking economics); null when priced or unsaid, and when its effect names none of its campaign's priced revenue lines (its revision's valueBasis.unpriced says no_revenue_line)
    - `findings` object[], required: The facts its verdict rests on, strongest first: a review's, carried unchanged by a person's later revision; empty for an action a person created
      - `text` string, required: One sentence
      - `stance` 'supports' | 'against', required: supports: a fact the verdict rests on; against: one that weighs against it
      - `citations` object[], required: Each figure in the text (start and end, in UTF-16 code units) and the sources it rests on
        - `start` integer, required
        - `end` integer, required
        - `sources` union[], required
          - union
            - object: An evidence row of a publication the review read
              - …
            - object: A quote the review recorded from a page
              - …
    - `createdAt` string, date-time, required
    - `createdByKind` 'person' | 'api_key' | 'automation' | 'review' | 'unknown', nullable, required
    - `firstSuggestedAt` string, date-time, required
    - `lastStateChangeAt` string, date-time, required
    - `dismissedAt` string, date-time, nullable, required
    - `dismissalReason` string, nullable, required
    - `implementation` AlphaImplementation2, required: Implementation tracking: who decides its status and the latest website check
      - `statusControl` 'automatic' | 'manual', required
      - `latest` object, nullable, required
        - `checkId` string, uuid, required
        - `observedAt` string, date-time, required
        - `finding` 'confirmed' | 'partial' | 'not_seen' | 'unavailable' | 'removed' | 'already_present' | 'manual', required
        - `summary` string, required
        - `criteria` object[], required
          - `criterionId` string, required
          - `requirement` string, nullable, required
          - `scope` string, nullable, required
          - `assessment` 'met' | 'missing' | 'unknown', required
          - `quote` string, nullable, required
          - `explanation` string, required
          - `sourceUrls` string[], required
        - `missingOrUncertainScope` string[], required
        - `change` string, nullable, required
        - `sources` object[], required
          - `evidenceId` string, required
          - `requestedUrl` string, uri, required
          - `finalUrl` string, uri, nullable, required
          - `status` integer, nullable, required
          - `fetchedAt` string, date-time, required
          - `byteLength` integer, required
          - `sha256` string, nullable, required
          - `truncated` boolean, required
          - `error` string, nullable, required
        - `application` 'applied' | 'no_effect' | 'superseded', required
        - `applicationReason` string, nullable, required
        - `assessedRevisionId` string, uuid, nullable, required
        - `settledAt` string, date-time, required
      - `completedBy` object, nullable, required
        - `checkId` string, uuid, required
        - `at` string, date-time, required
      - `reviewWarning` boolean, required
      - `decidedAt` string, date-time, nullable, required
    - `latestOutcome` AlphaLatestOutcome, required
      - `id` string, uuid, required
      - `completionEventId` string, uuid, required
      - `kind` 'metric' | 'page_traffic', required: metric: a metric an evidence product owns; page_traffic: Business Outcomes' page visits
      - `product` string, required
      - `metric` string, nullable, required: `<product>:<metric>`; null for page traffic
      - `status` 'measured' | 'unavailable', required
      - `comparison` object, required: The periods compared, before and after
      - `result` object, required: The metric owner's numbers
      - `sourceRefs` JsonValue[], required
        - union
          - string
          - number
          - boolean
          - JsonValue[]
          - object
      - `measuredAt` string, date-time, required
    - `conversation` object, nullable, required
      - `id` string, uuid, required: The action's Ship with Alpha conversation
      - `failed` boolean, required: Its latest turn failed (a stop is not a failure)
  - `eventIds` string[], required: Every event recorded, in order: the status change, a note it could not carry, and the change of control when a person or key took the action from automation; empty when it changed nothing
  - `revisionId` string, uuid, nullable, required: The content revision written; null without content

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `402`: Billing refused the write: the code names the reason and `details.reason` carries it.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/5241805fe425?raw)