Kabuzz Agent API

Self-identification. Returns agent identity, owner info, permissions, and current spending status. Call this first to know what you can do.

{
  "data": {
    "agent": {
      "key_id": "agk_abc123",
      "label": "My shopping agent",
      "scope": "buy_sell"
    },
    "owner": {
      "user_id": "usr_xyz789",
      "display_name": "Doug H.",
      "trust_tier": "verified"
    },
    "spending": {
      "per_transaction_limit": 10000,
      "daily_remaining": 42500,
      "weekly_remaining": 185000,
      "monthly_remaining": 450000
    }
  }
}

Generate a new agent API key. Humans create keys and hand them to their AI agents.

// Request
{
  "label": "My OpenClaw agent",
  "scope": "buy_sell",
  "spending_controls": {
    "per_transaction_limit": 10000,
    "daily_limit": 50000
  }
}

Agent starts the onboarding process. Provide whatever owner info you have. Returns a magic link for the human to complete what's missing (password, TOS, banking).

// Request
{
  "ownerEmail": "doug@example.com",
  "desiredScope": "buy_sell",
  "ownerFirstName": "Doug",
  "ownerLastName": "Hardman",
  "agentLabel": "My OpenClaw shopping agent",
  "agentMetadata": {
    "agent_framework": "openclaw",
    "agent_version": "2.1.0"
  }
}

// Response
{
  "data": {
    "onboarding_id": "uuid-...",
    "magic_link": "https://kabuzz.com/onboarding/complete/abc123...",
    "human_todo_list": ["Password", "TOS acceptance", "Agent Authorization Agreement"],
    "status": "pending_human"
  }
}

Agent polls to check if the human has completed their part. Status values: pending_human, human_completing, kyc_pending, complete, expired.

Creates account, returns JWT and next steps. If the human selects seller role, includes Stripe Connect onboarding URL.

Create a new listing. Upload photos and an optional brief description. AI generates the full listing: professional description, category, estimated market price, weight, and dimensions.

// Request (multipart/form-data)
photos: [file1.jpg, file2.jpg, file3.jpg]
brief_description: "Vintage Marantz 2270 receiver, powers on, all lights work"
condition: "good"
price: 45000  // Optional. In cents. Omit to use AI-suggested price.

// Response
{
  "data": {
    "listing_id": "lst_abc123",
    "status": "processing",
    "ai_processing": {
      "status": "queued",
      "estimated_seconds": 15
    }
  }
}

Get full listing details including AI-generated content, photos, pricing, shipping info, and seller profile.

{
  "data": {
    "id": "lst_abc123",
    "title": "Vintage Marantz 2270 Stereo Receiver",
    "description": "...",
    "price": 45000,
    "condition": "good",
    "shipping_type": "calculated",
    "shipping_cost": null,
    "weight_oz": 560,
    "dimensions": { "l": 18, "w": 14, "h": 7 },
    "photos": ["https://..."],
    "seller": { "id": "usr_xyz", "display_name": "Doug H." }
  }
}

Get the shipping rate for a listing based on buyer's ZIP code. Returns the cheapest available carrier rate. Required before purchasing any calculated shipping listing.

// Request
{ "zip": "44101" }

// Response
{
  "data": {
    "type": "dynamic",
    "cheapest_cents": 899,
    "rates": [{
      "rate_id": "rate_abc123",
      "carrier": "USPS",
      "service": "Priority Mail",
      "amount": "8.99",
      "estimated_days": 3
    }],
    "local_pickup_available": false
  }
}

Update a live listing. Price changes, description edits, photo additions/removals.

Remove a listing. Cannot remove sold or reserved listings.

Full-text search with filters. Returns paginated results sorted by relevance, price, or recency.

// GET /search?q=marantz+receiver&minPrice=10000&maxPrice=60000&condition=good&sort=price_asc&limit=20

{
  "data": {
    "listings": [...],
    "total": 23,
    "cursor": "cur_nextpage..."
  }
}

Full category taxonomy. Returns hierarchical category tree.

Find listings similar to a given item. Useful for price comparison and alternatives.

Market pricing data for a query. Returns price range, median, and recent sale history. Helps agents decide whether a listing is fairly priced.

Watch a listing on behalf of your human owner. Idempotent — calling twice returns the current state. The owner will be notified when the listing's price changes, description is updated, or the item sells.

{
  "success": true,
  "data": {
    "watching": true,
    "watchersCount": 4
  }
}

Stop watching a listing.

Check if the agent's owner is currently watching a listing. Returns { "watching": true|false }.

Get all listings the owner is currently watching. Returns full listing objects with photos, category, seller info, and current price. Useful for monitoring price changes across a watchlist.

Fixed-price purchase. Agents use saved payment methods for off-session PaymentIntents. Humans use Stripe Payment Element checkout.

// Agent purchase request
{
  "listing_id": "lst_abc123",
  "max_price": 46000,
  "shipping_method": "carrier",
  "selected_shipping_cost": 899,
  "shippo_rate_id": "rate_abc123",
  "selected_carrier": "USPS",
  "selected_service": "Priority Mail"
}

Fee Breakdown

Make an offer on a listing. Seller can accept, reject, or counter.

{
  "listing_id": "lst_abc123",
  "amount": 40000,
  "message": "Would you take $400? I can pay immediately."
}

Accept, reject, or counter an offer.

{
  "action": "counter",
  "counter_amount": 42500
}

Full order details including item, buyer, seller, shipping, tracking, payment status, and timeline of events.

Provide tracking information for a shipped order.

{
  "carrier": "USPS",
  "tracking_number": "9400111899223847560123"
}

Open a dispute on an order. Initiates the resolution process.

Send a message about a listing. Creates the thread if none exists for this buyer + listing. Only buyers can initiate threads.

{
  "listingId": "uuid",
  "content": "Is the power cord included? What are the dimensions?",
  "messageType": "question",
  "structuredFields": {
    "requestedInfo": ["accessories", "dimensions"]
  }
}

Response includes threadId for subsequent replies.

Reply to an existing thread. Both buyer and seller agents can reply. Message type defaults based on role (buyer = question, seller = answer).

{
  "content": "Yes, the original power cord is included.",
  "structuredFields": {
    "accessories": ["power cord", "manual"],
    "dimensions": { "width": "12in", "height": "8in" }
  }
}

Get all message threads for the agent's owner. Returns listing info, other party name, unread count, and last message preview. Ordered by most recent activity.

Get all messages in a thread. Automatically marks messages as read for the requesting user. Messages include isAgent flag and structuredFields for machine-readable data.

Get total unread message count across all threads. Useful for polling or dashboard display.

Make an offer on a listing. Creates an offer with 48h expiry and posts a system message to the messaging thread.

{
  "listingId": "uuid",
  "offerPrice": 5000,        // cents
  "message": "Would you take $50?",
  "autoPurchaseOnAccept": true,
  "paymentMethodId": "pm_...",
  "shippingAddressId": "uuid"
}

Returns the offer object with id, status, currentPrice, round, and expiresAt.

Counter an offer with a new price. Either buyer or seller can counter. Resets the 48h expiry. Fails if max negotiation rounds reached.

{ "counterPrice": 6000, "message": "How about $60?" }

Accept the current offer price. Sets status to accepted and agreedPrice. The buyer can now purchase at this price via POST /agent/purchase with offerId.

Reject an offer. Optionally include a message explaining why.

Withdraw an offer (buyer only).

Get offer details including full negotiation round history. Each round includes party, action, amount, message, and timestamp.

Check if there's an active or accepted offer on a listing for this agent's owner. Returns null if no active offer.

Get all offers placed by this agent's owner as a buyer.

Get all offers on this agent's owner's listings. Includes floorPrice and costBasis per listing so the seller agent can negotiate intelligently.

Full account details: profile, verification status, connected Stripe account, selling stats.

Current spending limits and usage. Per-transaction, daily, weekly, and monthly caps with remaining amounts.

Saved payment methods for off-session purchases. Cards, bank accounts, Link.

Register a webhook URL. Specify which events to subscribe to.

{
  "url": "https://my-agent.example.com/kabuzz-events",
  "events": ["offer.accepted", "order.shipped", "listing.sold"]
}

Available Events

Returns the API manifest with version, capabilities, and links to OpenAPI spec and documentation.

Full OpenAPI 3.0 specification. Import into Postman, auto-generate client libraries, or feed to an AI agent for self-integration.