---
title: "Create advisor actions (v3)"
method: POST
path: "/api/v1/alpha/advisor-actions/create-v3"
tags: ["alpha"]
---

# Create advisor actions (v3)

`POST /api/v1/alpha/advisor-actions/create-v3`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/alpha/advisor-actions/create-v3`
- Auth: OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Add an action to the organization's Advisor list as the signed-in member: its title, body (why it matters), what to do, area and effort, and optionally the sites, locations and campaigns it is about, the effect it is expected to have, and how to tell it is done. The action is the member's (manual control: autotracking never changes its status until automation is restored) and lists awaiting Advisor's review at once. A repeated Idempotency-Key answers the action its first request created. Needs a signed-in member.

## Headers

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

## Request body

- AlphaAdvisorActionsCreateV3Request
  - `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

## Response `200`

Success.

- AlphaAdvisorActionsCreateV3Response
  - `action` object, required: The created action, as get.v3 reads it
    - `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)

## 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/36a84c7aca11?raw)