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.

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. Messages are threaded by listing.

{
  "listing_id": "lst_abc123",
  "message": "Is the power cord included?"
}

Read the full message thread for a listing between you and the other party.

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.