# Cracked (V4): skill for your AI

Cracked is a marketplace for AI-made song ads: make ads with Cracked's song engine, sell them through Cracked, share it as an affiliate, or buy licenses and Weekly ads. This file is generated from the site's own command list.

## How to call it
- Your person makes you a key at https://v4.cracked.app/ai (they pick your scope: make, sell, spend, manage). Send `Authorization: Bearer <key>` on every call. The key works for one organization.
- Read: `GET https://v4.cracked.app/api/v1/<query>`. Act: `POST https://v4.cracked.app/api/v1/<command>` with a JSON body of the command's fields plus `request_key` (any new string). Sending the same request again with the same request_key is safe: you get the first answer back, never a second purchase or call.
- Every answer has `status` (done, waiting, refused, failed) and `said` (one line). A refusal says what to do next. `waiting` means it spends money: your person says yes at /ai; ask GET /api/v1/approval_requests/<id>.
- Test mode: Stripe's and PayPal's sandboxes. No real money moves.

## What your scope words mean
- `make`: call engines and make media
- `sell`: sell: submit media, claim leads, share affiliate links, report sales
- `spend`: spend money: orders, deposits, recoveries
- `manage`: manage the organization: members, payout email, AI keys, programs
- `review`: review (Cracked's own work: media for sale, affiliates, payouts, leads)

## Recipes

### Make a song ad for a shop (and download it)
1. GET /api/v1/my_credit_entries: your credits. A call to the song engine is 8 credits; the free sample engine is 0 (its ads can't be sent or sold).
2. No credits? `order` {price: "pri_credits_60"} (60 credits, $20): it waits for your person's yes (approval_requests), then your person pays at the checkout_url.
3. `call_engine` {engine: "ast_song_engine", store_url, name, brief, for_lead?}: answers a usage id. GET /api/v1/usage/<id> every 30 s until status is done (3 to 6 minutes).
4. Its made_media_asset_id is your media, owned by your organization. Download: GET /media/<asset id>/file with your key.

### Sell your media through Cracked
1. `submit_media` {media}: sends it to Cracked's review. If Cracked accepts, it holds a distributor row and sells a $49 license at /p/<slug>; each sale earns your organization 60%.
2. GET /api/v1/my_media shows each version's decision and, once on sale, its product slug. GET /api/v1/my_earnings shows each earning and when it clears.
3. Pitching a shop first? GET /api/v1/leads, then `claim_lead` {lead}: yours alone for 7 days, with its contacts. Make the ad with for_lead so the shop's purchase links back to it.

### Buy the course, the free skill files, a license or Weekly ads
1. GET /api/v1/products lists every product and its prices (what each grants: credits, or a holder, licensee, subscriber or owner row).
2. `order` {price}: a $0 price (the free skill files) is done at once and gives you a holder row; any other answers a checkout_url your person pays (Stripe test card 4242 4242 4242 4242).
3. A subscriber to Weekly ads gets ads made for it: GET /api/v1/my_ads_to_decide, then `decide_ad` {version, decision: accepted|rejected}. Each accepted ad is a licensee row (up to the period's quota).
4. A refund within the price's window: `refund_order` {order}. Its rows end; earnings it made get negatives.

### Share Cracked as an affiliate
1. `join_program` {program: "ast_affiliate_program"}: a paused affiliate row until Cracked approves it.
2. Once active, your link is https://v4.cracked.app/?ref=<your affiliate row id> (GET /api/v1/my_affiliate_rows). Anyone who signs up through it and pays makes you 10% of every order for 365 days, held 7 days.
3. A merchant's own program (pays_on sale_report) works the same: their store reports sales made through your link, and you earn their rate.

### Run your own program as a merchant (your own store)
1. `create_program` {title, pays_on: "sale_report", rate_bps: 1000, hold_days: 30}; `fund_program` {program, amount_cents}: it pays affiliates only from what it holds.
2. Approve affiliates: GET /api/v1/affiliate_asks, then `approve_affiliate` {affiliate, decision: approved}.
3. Your store reports each sale through an AI key with scope sell: `report_sale` {affiliate, external_order_id, amount_cents, evidence}; a refund: `reverse_sale` {external_order_id}. The same order id twice pays once.

### Money
1. `set_payout_email` {email}: where payouts go (PayPal sandbox in test mode).
2. GET /api/v1/my_balance: ready, held (and the first date one clears), owed back, paid. Payouts net everything you're owed; a payout is never $0.
3. Owe money back (a reversal after a payout)? It nets from your next earnings, or `pay_back` {earning}.

## Commands (POST /api/v1/<name>)

### `connect_ai`
connect your own AI for this organization: pick its scope (what it may do for you, within your own permissions) and get its key, shown once. A person only: an AI can't.
  - `name` (text): what to call it (Claude on my laptop)
  - `scope` (list, required): make, sell, spend, manage (only what you hold yourself)

### `revoke_ai`
revoke one of your AI's keys: it can do nothing from now on, even a request already on its way. A person only: an AI can't.
  - `agent_connection` (id, required): the connection's id

### `decide_approval`
say yes or no to something your AI asked to do that spends money; yes runs it now, with every check again. A person only: an AI can't.
  - `approval_request` (id, required): the approval request's id
  - `decision` (text, required): approved or rejected

### `create_program`
create your organization's own program: what it pays on (order, usage, view_report or sale_report), its rate, window and hold. Needs `manage`.
  - `title` (text, required): its name (TofuGo affiliates)
  - `pays_on` (text, required): sale_report for sales on your own store
  - `rate_bps` (int, required): the share in basis points: 1000 = 10%
  - `window_days` (days): how long after the click a sale still counts (blank: always)
  - `hold_days` (days): how long each earning waits before it can be paid (30 for outside sales; minutes on a test program)

### `join_program`
ask to be an affiliate of a program (free, never sold): a paused affiliate row until the program's owner approves it; then your link carries that row's id. Needs `sell`.
  - `program` (id, required): the program's asset id (GET /api/v1/programs)

### `approve_affiliate`
a program's owner approves (or ends) an affiliate's row on it. Needs `manage`.
  - `affiliate` (id, required): the affiliate row's id
  - `decision` (text, required): approved or ended

### `fund_program`
put money into a program so it can pay its affiliates (a deposit through a Stripe test checkout); a program never pays more than it holds. Needs `spend`. Spends money: an AI's ask waits for its person's yes.
  - `program` (id, required): your program's id
  - `amount_cents` (cents, required): how much, in cents (20000 = $200)
  - `pay_with` (text): checkout (default) or payment_intent

### `report_sale`
a merchant's store reports a sale on its own site made through an affiliate's link: the affiliate earns the program's share, cleared after its hold (a sale over $500 waits for Cracked to check the evidence); the same external_order_id twice pays once. Needs `sell`.
  - `affiliate` (id, required): the affiliate row id the buyer's link carried (?ref=)
  - `external_order_id` (text, required): your store's own order id
  - `external_customer_ref` (text): your store's own reference for the buyer (never a person's details)
  - `amount_cents` (cents, required): what the buyer paid, in cents
  - `currency` (text): ISO currency (USD)
  - `evidence` (text): a link to the order or receipt

### `reverse_sale`
a merchant reports that a sale it reported was refunded: a new reversed report, and the affiliate's earning gets its negative. Needs `sell`.
  - `external_order_id` (text, required): your store's order id, as first reported

### `pay_back`
pay back a reversal you owe (money you were paid for a sale that was later refunded) through a Stripe test checkout: a recovery payment. Needs `spend`. Spends money: an AI's ask waits for its person's yes.
  - `earning` (id, required): the negative earning (the reversal) you owe
  - `pay_with` (text): checkout (default) or payment_intent

### `call_engine`
call an engine (the song engine makes a song ad for a shop): spends the engine's credits_per_call from your wallet; the media it makes is your organization's. Needs `make`.
  - `engine` (id, required): the engine's asset id (GET /api/v1/engines)
  - `store_url` (url, required): the shop's website the ad is about
  - `name` (text, required): the shop's name, as it should be sung and shown
  - `brief` (text): what the ad should say: the offer, the facts, what never to say
  - `for_lead` (id): the lead asset the ad is made for (you're pitching it)
  - `for_organization` (id): the organization the ad is made for (a subscriber's ads)

### `set_engine_access`
an engine's owner pauses, resumes or limits (quota) one organization's user row on it. Needs `manage`.
  - `access` (id, required): the user row's id
  - `status` (text): active or paused
  - `quota` (int): how many calls in all it may make (blank: no limit)

### `set_payout_email`
set where your organization's payouts go (a PayPal address; sandbox in test mode). Needs `manage`.
  - `email` (email, required): the PayPal address

### `rename_organization`
rename your organization. Needs `manage`.
  - `name` (text, required): the new name

### `add_member`
add a person to your organization by email, with a role (owner, admin, member) and, for a member, permissions (make, sell, spend, manage, review). Needs `manage`. A person only: an AI can't.
  - `email` (email, required): their email; they sign in with it
  - `role` (text, required): owner, admin or member
  - `permissions` (list): for a member: make, sell, spend, manage, review

### `end_membership`
leave your organization, or (an owner or admin) end someone's membership; an organization always keeps one live owner. A person only: an AI can't.
  - `membership` (id, required): the membership's id (yours, to leave)

### `submit_media`
send your media's latest version to be decided on: to Cracked's review to be sold through Cracked, or (Cracked's ads for a subscriber) to that customer. Needs `sell`.
  - `media` (id, required): the media asset's id

### `decide_ad`
a subscriber accepts or rejects an ad Cracked made for it this period; accepting gives it a licensee row from that period's subscriber row (used + 1, up to its quota). Needs `manage`.
  - `version` (id, required): the media version's id (GET /api/v1/my_ads_to_decide)
  - `decision` (text, required): accepted or rejected

### `publish_product`
publish a product for an asset you own (or that Cracked distributes) at its own address /p/<slug>; add its prices with add_price. Needs `sell`.
  - `asset` (id, required): the asset it sells
  - `title` (text, required): the product's name
  - `slug` (text, required): its address: lowercase letters, digits and dashes
  - `description` (text): what the buyer gets

### `add_price`
add a price to your product: what it costs and what it grants (credits, or a holder/licensee/subscriber/owner row, with a quota and how long it lasts), and its refund window. Needs `sell`.
  - `product` (id, required): your product's id
  - `amount_cents` (cents, required): the price in cents (0 for free)
  - `grants_role` (text): holder, licensee, subscriber (needs interval) or owner (a buyout)
  - `grants_credits` (int): credits it adds to the buyer's wallet
  - `grants_quota` (int): how many it allows (a subscriber's ads per period)
  - `grants_days` (days): how long the granted row lasts, in days (blank: no end)
  - `interval` (text): for a subscription: '1 month', '1 week', or minutes on a test price ('3 minutes')
  - `keeps_license` (bool): a buyout: the seller keeps a licensee row
  - `refund_days` (days): how long after paying a refund can still come (earnings wait for it)

### `retire_price`
stop selling a price (it stays on the orders that bought it; a price is never edited once ordered). Needs `sell`.
  - `price` (id, required): the price's id

### `retire_product`
take a product off sale. Needs `sell`.
  - `product` (id, required): the product's id

### `withdraw_media`
the owner stops Cracked selling its media: the distributor row ends and Cracked's products for it come off sale (licenses already sold stay). Needs `sell`.
  - `media` (id, required): your media's id

### `order`
buy a price for your organization: a $0 price is done at once; any other answers a Stripe checkout_url (test mode) your person opens to pay. Needs `spend`. Spends money: an AI's ask waits for its person's yes.
  - `price` (id, required): the price's id (GET /api/v1/products lists them)
  - `ref` (text): a signed referral token, if someone's link brought you (pages fill it in)
  - `pay_with` (text): checkout (a Stripe page your person opens; the default) or payment_intent (a PaymentIntent your side confirms)

### `refund_order`
refund an order: its seller any time; its buyer within the price's refund window. Its access rows end and its earnings get their negatives.
  - `order` (id, required): the order's id

### `cancel_subscription`
stop a subscription's next charges; the period already paid runs to its end. Needs `spend`.
  - `order` (id, required): the subscription's order id

### `claim_lead`
claim a lead to pitch it: yours alone for its claim_days (7 days), so you see its contacts; one live claim per lead. Needs `sell`.
  - `lead` (id, required): the lead's asset id (GET /api/v1/leads)

### `release_claim`
let a lead you claimed go, so someone else can pitch it. Needs `sell`.
  - `lead` (id, required): the lead's asset id

### `add_channel`
add a social account your organization posts on (tiktok, youtube, instagram, x, other). Needs `sell`.
  - `platform` (text, required): tiktok, youtube, instagram, x or other
  - `handle` (text, required): the account's handle (@name)

### `record_publication`
record that your organization posted media (yours, or licensed to you) on one of its channels. Needs `sell`.
  - `channel` (id, required): your channel's id
  - `media` (id, required): the media asset posted
  - `url` (url, required): the post's link

### `report_views`
report a publication's view count as of now. Needs `sell`.
  - `publication` (id, required): the publication's id
  - `views` (int, required): its views now

## Queries (GET /api/v1/<name>)
- `me`: who you are: your account, the organization you act for, your membership, its credits, and (an AI) your scope
- `my_assets`: the assets your organization owns (its live owner rows), newest first
- `my_asset_access`: every asset_access row your organization holds (any role, live and ended), newest first
- `my_media`: media your organization owns or holds a license to, with its versions (file, decision) and who it was made for
- `my_usage`: your organization's engine calls (usage), newest first: status, credits, the media each made
- `usage` /<id>: one engine call: GET /api/v1/usage/<id> (status running, done or failed; made_media_asset_id when done)
- `my_credit_entries`: your wallet: the balance and every credit_entries row (bought, spent, returned, refunded)
- `my_orders`: orders your organization placed, newest first, with their price, product and payments
- `my_sales`: orders of your organization's products (you're the seller), newest first
- `my_earnings`: money owed to your organization: each earning, its source (order, usage, view or sale report), when it clears (held until), and whether a payout paid it
- `my_balance`: what your organization is owed right now: ready (cleared), held (with the first date one clears), owed back, and paid so far
- `my_payouts`: payouts sent to your organization, with the earnings each settled
- `my_approval_requests`: what your AIs asked to do that spends money, and what came of it
- `approval_requests` /<id>: one approval request: GET /api/v1/approval_requests/<id> (status waiting, approved, rejected or expired, and its result)
- `my_agent_connections`: your AIs' keys for this organization (scope, created, revoked)
- `members`: the people in your organization (memberships)
- `products`: products on sale, each with its address and live prices (what each grants)
- `engines`: engines you can call and what a call costs in credits
- `programs`: programs you can join as an affiliate: who runs it, what it pays on, its rate, window and hold
- `my_programs`: programs your organization runs, their cash (deposits and recoveries minus what was paid) and their affiliates
- `my_affiliate_rows`: your organization's affiliate rows (on programs: your links; on customers: who you brought) and referrer rows (leads you brought who haven't paid yet)
- `leads`: Cracked's lead list: leads to pitch, whether each is claimed and until when; contacts (website, handles) only for its claimant and Cracked
- `course`: the course's lessons (their words only for a holder of the course)
- `files`: file assets (free skill files and the like): what's in each, and its download link if your organization holds it
- `my_ads_to_decide`: a subscriber's ads: this period's subscriber row (quota, used) and the ads Cracked sent your organization to accept or reject
- `my_sale_reports`: sale reports your organization's store sent (as a merchant), with the affiliate each paid
- `my_channels`: your organization's channels, their publications and latest views
- `affiliate_asks`: affiliate rows waiting for your program's approval