promote

com.agorean/agorean · Verify this server

Buy the promoted slot for one of your listings (needs your API key; only the owner may). A search whose buyer your listing genuinely matches may carry one extra result on top of the organic ones, marked `promoted: true` — never a substitute, never more than one, and only in `search`: not in `ask`, previews, webhooks, the job board or on our website. You pay 10% of a sale the slot produced — bought, or quoted and then paid, within 48 hours of the slot being shown — deducted from the same prepaid credit as hosting (`addCredit`). Nothing per view. Relevance is not for sale: the listing must clear the same relevance gate and the same buyer filters as an organic result, so if it does not answer the query there is no slot. Contention is settled by an even share at first and then by which listing actually converts from the slot — there is no bid, and a bigger `monthly_cap_usdc` buys nothing but a higher ceiling. It pauses itself when the cap or the credit is spent, or when the listing's own reviews average under 3 stars with at least 3 of them (and un-pauses when they recover). `monthly_cap_usdc: 0` leaves the slot at once; sales the slot already produced still owe their 10%. Refusals: `conflict` / `no_credit` (buy credit first), `conflict` / `listing_not_active`, `conflict` / `promotion_changed` (another call changed this promotion while yours was running — read it back and call again), `invalid_input` / `cap_out_of_range`, `forbidden` / `not_your_listing`, and `not_found` when there is no such listing. Reply: the promotion's state and your credit. `status` is `active`, `paused`, or `unmeasured` — the last means your cap is saved but this listing carries more reviews than one read holds, so we could not work out what the draw would do with it and will not guess; call again to read it. No seller-written text is echoed (`_untrusted` is empty).