Skip to main content
POST
Create Recommendations

Authorizations

Authorization
string
header
required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

Headers

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-09-11-1"

Body

application/json
input
string
required

What the owner wants, in their own words. Up to 1000 characters.

Maximum string length: 1000
Example:

"I sell $79 customized gym straps. The number of purchases per day fell from 84 to 66 since June and my ads cost per signup doubled to $38. Half the leads never open the checkout. I want to win back churned visitors and lift conversion without cutting the price, and I can spend up to $500 this month on it."

account_id
string

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

Example:

"biz_xxxxxxxxxxxxxx"

Response

recommendation queued

account_id
string
required

The account this recommendation is for, prefixed biz_

Example:

"biz_xxxxxxxxxxxxxx"

action_type
string | null
required

The playbook action this card recommends, or null for an untyped card; new values may be added, so handle unknown types gracefully

Example:

"improve_landing_page"

created_at
string
required

When the recommendation was created, as an ISO 8601 timestamp.

Example:

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

executed_at
string | null
required

When the card was run, as an ISO 8601 timestamp, or null

Example:

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

id
string
required

Economic intelligence ID, prefixed reca_

Example:

"reca_xxxxxxxxxxxxxx"

input
string | null
required

What the owner asked for, in their own words, when this recommendation was requested, or null when the engine chose the action on its own

Example:

"Grow revenue"

prompt
string | null
required

The step-by-step brief Whop AI executes when the card is run, or null

Example:

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

reasoning
string | null
required

The signal and number the recommendation rests on, or null

Example:

"Revenue fell by 20%."

status
enum<string>
required

queued once requested and not yet picked up; pending while the engine is generating; ready when the card is written and the owner can run it; executed once it was run; superseded when a newer card of the same action type replaced it; failed when the engine had nothing to recommend for the request

Available options:
queued,
pending,
ready,
executed,
superseded,
failed
Example:

"superseded"

superseded_at
string | null
required

When a newer card replaced this one, as an ISO 8601 timestamp, or null

Example:

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

title
string | null
required

The recommendation as the owner sees it: one command with the payoff, or null until the engine has written the card

Example:

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