Skip to main content
PATCH
Update Recommendation

Authorizations

Authorization
string
header
required

An Account API key, an App API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.

Headers

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-09-29"

Path Parameters

id
string
required

Recommendation ID, prefixed reca_.

Query Parameters

account_id
string

Account ID, prefixed biz_. Defaults to the API key's own account.

Body

application/json
input
string

What you want the replacement recommendation for, in your own words. Up to 1000 characters. Sent when superseding, it directs the generation that replaces the rejected recommendation.

Maximum string length: 1000
Example:

"Focus on returning buyers instead"

result_id
string

With status: executed, the ID of what the run produced or changed, and the recommendation's result_url becomes where to view it: an ad (ad_), ad group (adgrp_) or ad campaign (adcamp_), a website (app_), a product (prod_), a plan (plan_), a checkout link (ch_), a promo code (promo_), or an experience (exp_). Without result_id or result_page, result_url links to the resource the recommendation was about, when it names one. Send only one of result_id, result_page and result_url.

Example:

"prod_xxxxxxxxxxxxx"

result_page
enum<string>

With status: executed, the page where the run's result can be seen when it is not one resource, such as the checkout links list or the store page. The recommendation's result_url becomes that page on the account's dashboard, or its store page for store_page.

Available options:
home,
products,
ads,
websites,
checkout_links,
tracking_links,
promo_codes,
payments,
customers,
affiliates,
analytics,
store_page
Example:

"promo_codes"

result_url
string

With status: executed, where to view what was produced when it is outside Whop. An http or https URL. Prefer result_id for anything on Whop.

Maximum string length: 2048
Example:

"https://atlas.whop.site/"

sentiment
enum<string>

A signed-in user can rate a recommendation as positive or negative. Can be sent alone or together with status.

Available options:
positive,
negative
Example:

"positive"

status
enum<string>

Use running to start a run of a ready recommendation, executed to record that it was carried out, incomplete to record that a running recommendation's run ended without carrying it out, superseded to reject a ready recommendation, or acknowledged to mark an executed run as seen; the recommendation stays executed and records acknowledged_at.

Available options:
running,
executed,
incomplete,
superseded,
acknowledged
Example:

"superseded"

user_feedback
string

An optional explanation of the rating or rejection. Negative feedback informs replacement recommendations.

Maximum string length: 2000
Example:

" Focus on returning buyers "

Response

recommendation superseded

account_id
string | null
required

ID of the account this recommendation is for, prefixed biz_, or null for personal onboarding.

Example:

"biz_xxxxxxxxxxxxxx"

acknowledged_at
string | null
required

When the executed run was first marked as seen, as an ISO 8601 timestamp, or null if it has not been.

Example:

"2026-01-01T12:00:00.000Z"

action_type
string | null
required

Type of action recommended, or null when no type is assigned. New values may be added; handle unknown types gracefully.

Example:

"scale_winning_ads"

ai_chat_id
string | null
required

The chat that ran the recommendation, shown only to the user who ran it, or null otherwise.

Example:

"aich_xxxxxxxxxxxxxx"

created_at
string | null
required

When the recommendation was created, as an ISO 8601 timestamp, or null for an unsaved recommendation.

Example:

"2026-01-01T12:00:00.000Z"

executed_at
string | null
required

When the recommendation was carried out, as an ISO 8601 timestamp, or null if it has not been.

Example:

"2026-01-01T12:00:00.000Z"

expected_tool_calls
object[] | null
required
id
string
required

Recommendation ID, prefixed reca_, or create_business for an unsaved setup recommendation. Authenticate and list again before executing an unsaved recommendation.

Example:

"reca_xxxxxxxxxxxxxx"

input
string | null
required

What you requested, in your own words, or null for recommendations generated without your input.

Example:

"more sales from ads"

inputs
object[]
required
prompt
string | null
required

Step-by-step instructions for Whop AI, or null when no instructions are available.

Example:

"Create a 20% off promo code for my members."

reasoning
string | null
required

Evidence and metrics supporting the recommendation, or null when no reasoning was provided.

Example:

"Capped 9 of 14 days."

result_url
string | null
required

Where to view what the run produced, such as the published website or created product, or null when the result is only in the chat.

Example:

"https://atlas.whop.site/"

run_by_user_id
string | null
required

The user who started the run, prefixed user_, or null if it has not run or was started without a user, such as with an API key.

Example:

"user_xxxxxxxxxxxxxx"

run_ended_at
string | null
required

When Whop AI's run ended, whether executed or incomplete, as an ISO 8601 timestamp, or null if it has not ended.

Example:

"2026-01-01T12:00:00.000Z"

run_started_at
string | null
required

When Whop AI started carrying out the recommendation, as an ISO 8601 timestamp, or null if it has not run.

Example:

"2026-01-01T12:00:00.000Z"

sentiment
enum<string> | null
required

How the user rated this recommendation, or null if they have not rated it

Available options:
positive,
negative,
null
Example:

"positive"

status
enum<string>
required

queued when awaiting generation; pending while generating; ready when available to run; running while Whop AI carries it out; executed when carried out; incomplete when Whop AI's run ended without carrying it out; superseded when rejected or replaced.

Available options:
queued,
pending,
ready,
running,
executed,
incomplete,
superseded
Example:

"executed"

superseded_at
string | null
required

When the recommendation was rejected or replaced, as an ISO 8601 timestamp, or null if neither has occurred.

Example:

"2026-01-01T12:00:00.000Z"

title
string | null
required

Recommended action and its expected benefit, or null until generated.

Example:

"Move $180 from 3 dead ad groups into BATCH#3, +1.7x return"

user_feedback
string | null
required

The user's written feedback, or null if they have not provided any.

Example:

null

target_url
string | null

Website URL selected for pixel setup, or null when no website was captured for this recommendation.

Example:

"https://example.com/join"