Agent

Buy a marketplace listing with the owner's money, within their limits

Changed on

Spends the API key owner's REAL money: charges the card they saved, only after they switched agent buying on and only within the per-purchase and per-day limits they set at https://oriva.io/settings/agent-buying. Use only when the owner has asked you to buy this listing; do not use to check a price (read the listing first) or to browse.

  • expectedAmountCents must be the exact current total; a different price is refused.
  • Always send an Idempotency-Key and reuse it when retrying the same purchase; a repeat returns the first attempt (200, repeat: true) instead of buying twice.
  • 201 bought. 202 not finished yet: it still counts against the limits, so do NOT buy again; check listAgentPurchases later.
  • 403 refused: true is final (switched off, over a limit, price changed, own listing...): do not retry; tell the owner the reason.
  • 402 the card was not charged.

Authorised only by a personal access token (Bearer oriva_pk_...), never a browser session. Served by https://oriva.io, not api.oriva.io.

post/api/agent/purchases

Request

  • Base URL: https://oriva.io
  • URL: https://oriva.io/api/agent/purchases
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Your id for this purchase attempt, up to 200 characters. Resending the same key returns the first attempt instead of buying again. Always send one, and reuse it when retrying the same purchase. If omitted, the SDK, CLI and MCP server generate one and report it.

Request body

listingIdstring uuid required

The marketplace listing (entry) id to buy.

expectedAmountCentsinteger required

The exact current total you agreed to pay, in cents (1200 = 12.00). If the listing price differs, the purchase is refused before any charge.

variantIndexinteger

Which of the listing's price variants to buy (0-based). Omit for the default.

Response

Repeat of an earlier request with the same Idempotency-Key. Nothing new was bought.

repeattrue required
messagestring required

Changes