← Back to AuctionAI overview
A

Kernvel AI Auction API Reference

The developer REST API for reading and managing your store's auctions, bids, and webhooks.

AuctionAI API reference

Use the public API to integrate your store's auctions with your own tools. It is a scoped subset of the app, not every admin operation. The current public schema is available at OpenAPI JSON; use it for complete request/response validation, including inherited fields.

Base URL and keys

Base: https://auctionai.kernvellabs.com/api/public/v1. Create a key in API Keys in the app. Save the secret immediately; it is shown once. Revoke/replace a lost key. Keys belong to one store; requests do not select another store.

curl https://auctionai.kernvellabs.com/api/public/v1/auctions \
  -H 'Authorization: Bearer kv_auc_live_REPLACE_WITH_YOUR_KEY'

X-API-Key is also supported. Keep keys on your server, never in storefront/browser code. Only /ping is an unauthenticated business endpoint. The public schema is also downloadable without a store key. Customer/winner contact scopes require explicit consent and eligible plans.

Test keys are available on every plan within its scope limits. Test mode suppresses real orders, charges and emails; it is not a separate complete copy of your store. Start with read-only integrations. X-Kernvel-Test-Mode: true identifies authenticated test responses. Live access also requires an eligible active subscription.

Plan access

Plan Requests/min per key Maximum keys Live keys Webhook endpoints Grantable scopes
Free 60 2 False 0 account:read, auctions:read, bids:read, products:read
Starter 120 5 True 0 account:read, auctions:read, bids:read, products:read
Pro 300 25 True 5 account:read, webhooks:manage, auctions:read, auctions:write, auctions:manage, bids:read, bids:write, bidders:manage, winners:read, products:read, customers:read
Enterprise 600 100 True 20 account:read, webhooks:manage, auctions:read, auctions:write, auctions:manage, bids:read, bids:write, bidders:manage, winners:read, products:read, customers:read

Free has test keys only. Starter has read-only live keys and no winner/customer PII scopes. Pro and Enterprise can grant write/manage and PII scopes as listed. Requested permissions are intersected with plan permissions; a scope existing in the catalog does not imply a route exists for every possible operation.

Request contract

  • Send JSON with Content-Type: application/json.
  • Lists use opaque cursor pagination, default 25, maximum 100. Pass next_cursor back unchanged. Auction list supports its documented status filter.
  • Send a unique Idempotency-Key on writes; required routes are marked below. A matching replay returns the saved result; reusing a key for different input conflicts. The configured default replay window is 24 hours.
  • Money in serialized responses uses decimal strings with currency; request types are specified by the schema, including numeric amount fields. Timestamps use UTC ISO-8601. Preserve precision in your integration.
  • Lists return object, data, has_more and next_cursor. Single resources have typed string IDs (auc_, bid_, prod_, whk_, shop_).
  • Errors use application/problem+json with status/code/detail/request ID. Expect 400 validation/input, 401 key/authentication, 403 scope/plan, 404 missing/cross-store, 409 conflict/replay, 429 rate limit, and 503 disabled API. Read the actual code/detail rather than relying only on HTTP status.
  • Quote X-Request-Id in support requests. Authenticated responses carry applicable rate-limit headers; on 429 respect Retry-After. Not every unauthenticated/error response has a computed per-key quota.

Routes

Paths below are relative to the base URL. This inventory is generated from the current route decorators and dependencies. Read the OpenAPI schema for query/body requirements and eligibility rules. API actions still obey auction deadlines, ownership and money-safety checks.

Method Path Required scope Idempotency key
GET /ping none —
GET /account account:read —
GET /account/usage account:read —
GET /auctions auctions:read —
GET /auctions/{auction_id} auctions:read —
GET /auctions/{auction_id}/winner winners:read —
POST /auctions auctions:write required
PATCH /auctions/{auction_id} auctions:write required
DELETE /auctions/{auction_id} auctions:manage required
GET /auctions/{auction_id}/bids bids:read —
POST /auctions/{auction_id}/bids bids:write required
POST /auctions/{auction_id}/buy-now bids:write required
GET /products products:read —
GET /products/{product_id} products:read —
POST /webhooks webhooks:manage —
GET /webhooks webhooks:manage —
GET /webhooks/{webhook_id} webhooks:manage —
DELETE /webhooks/{webhook_id} webhooks:manage —

Request and response fields

Generated declarations below include direct model fields and their validation expressions. OpenAPI resolves inherited options and nested types; do not omit those when generating a client.

PublicApiAccess

Field Type Source default / validation
live_keys bool required
max_keys int required
scopes list[str] required
rate_per_min int required
webhook_endpoints int required

PublicAccount

Field Type Source default / validation
object str 'account'
id str required
shop_domain str required
plan str required
subscription_status str required
currency str required
test_mode bool required
api_access PublicApiAccess required

PublicUsage

Field Type Source default / validation
object str 'usage'
plan str required
active_auctions int required
auction_limit int required
rate_limit int required
rate_limit_remaining int required

PublicAuction

Field Type Source default / validation
object str 'auction'
id str required
title str required
status str required
auction_type str required
currency str required
current_price Optional[str] None
starting_price Optional[str] None
reserve_price Optional[str] None
buy_now_price Optional[str] None
final_price Optional[str] None
total_bids int 0
unique_bidders int 0
product_id Optional[str] None
starts_at Optional[str] None
ends_at Optional[str] None
ended_at Optional[str] None
created_at Optional[str] None

PublicAuctionWinner

Field Type Source default / validation
object str 'auction_winner'
auction_id str required
winner_shopify_customer_id Optional[str] None
winning_bid_id Optional[str] None
final_price Optional[str] None
currency str required
won_at Optional[str] None
payment_status Optional[str] None

PublicAuctionCreate

Field Type Source default / validation
product_id str required
title Optional[str] Field(None, max_length=500)
description Optional[str] None
auction_type AuctionType AuctionType.STANDARD
visibility AuctionVisibility AuctionVisibility.PUBLIC
scheduled_start Optional[AwareDatetime] None
duration_hours int Field(default=24, ge=1, le=720)
starting_price float Field(ge=0)
reserve_price Optional[float] Field(None, ge=0)
buy_now_price Optional[float] Field(None, gt=0)
min_bid_increment float Field(default=1.0, gt=0)
currency str Field(default='USD', pattern='^[A-Z]{3}$')
popcorn_enabled bool False
payment_due_hours int Field(default=48, ge=1, le=168)

PublicAuctionUpdate

Field Type Source default / validation
title Optional[str] Field(None, max_length=500)
description Optional[str] None
visibility Optional[AuctionVisibility] None
extend_hours Optional[int] Field(None, ge=1, le=168)
buy_now_price Optional[float] Field(None, gt=0)
popcorn_enabled Optional[bool] None

PublicBid

Field Type Source default / validation
object str 'bid'
id str required
auction_id str required
amount str required
currency str required
status str required
source str required
created_at Optional[str] None

PublicBidCreate

Field Type Source default / validation
amount float Field(gt=0)
customer_id str Field(min_length=1, description='Shopify customer id to attribute the bid to')
customer_email Optional[str] None
customer_name Optional[str] None

PublicBuyNowCreate

Field Type Source default / validation
customer_id str Field(min_length=1, description='Shopify customer id to attribute the purchase to')
customer_email Optional[str] None
customer_name Optional[str] None

PublicProduct

Field Type Source default / validation
object str 'product'
id str required
title str required
description Optional[str] None
shopify_product_id Optional[str] None
sku Optional[str] None
condition Optional[str] None
currency str 'USD'
original_price Optional[str] None
image_url Optional[str] None
created_at Optional[str] None

PublicWebhook

Field Type Source default / validation
object str 'webhook_subscription'
id str required
url str required
events list[str] required
description Optional[str] None
env str required
is_active bool required
created_at Optional[str] None

WebhookCreate

Field Type Source default / validation
url str required
events list[WebhookEvent] Field(min_length=1)
description Optional[str] Field(None, max_length=255)

Webhooks

Pro/Enterprise can create subscriptions using webhooks:manage. The create response shows a signing secret once; save it securely. Subscribe only to event names accepted by the current schema. Envelopes contain event ID/type, API version, creation time and resource data; test/live subscriptions receive matching test/live events.

Verify X-Kernvel-Signature: t=<unix>,v1=<hmac> against the raw body using HMAC-SHA256 over <t>.<raw-body>, constant-time comparison and a bounded timestamp tolerance. Deduplicate event IDs and process asynchronously before returning success. Failed delivery retries use 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours backoff; repeated failures can disable the subscription. Delivery is best effort and should be reconciled against current resource state.

Version and help

The configured API date version is 2026-06-23, echoed in X-Kernvel-Api-Version. Follow the downloadable schema when updating clients. This reference makes no release-notice SLA promise. Contact Kernvel support with request ID and endpoint; never include keys.