API reference

Reference for the Cresva Storefront API. All Storefront endpoints use the base URL https://api.cresva.ai/api/storefront/{brandId}.

Management API

Management API preview

The brand-facing Management API (catalog CRUD, analytics, deployments, agent query logs) is in active development. Schemas and shapes below are stable. They describe the planned surface. The Storefront API documented further down is live today.

AuthenticationTokens, scopes, and security Rate LimitsHeaders, quotas, and best practices ProductsManage your product catalog QueriesAgent query logs and analytics TransactionsTransaction history and recording Trust ScoresBrand trust across platforms AnalyticsOverview, queries, and revenue VerticalsVertical profiles and attributes DeploymentsDeployment configs and stats Event StreamReal-time SSE events

Storefront API

GET/.well-known/acp.json

Retrieve the ACP discovery file for a domain. This is served at the domain root, not under the storefront base URL.

Authentication: public key

Response

JSON

{
  "acp_version": "2.0",
  "storefront_url": "https://api.cresva.ai/api/storefront/brand_abc123",
  "brand_id": "brand_abc123",
  "brand_name": "Acme Co",
  "capabilities": ["search", "recommend", "compare", "negotiate", "transact"],
  "supported_currencies": ["USD", "EUR"],
  "documentation": "https://developers.cresva.ai/protocol/spec"
}

GET/products

List all products in the storefront catalog. Supports pagination.

Authentication: public key

Query Parameters

categorystringFilter by category path

offsetnumberPagination offset (default: 0)

limitnumberResults per page (default: 20, max: 100)

const products = await client.products.list({
  category: "electronics/audio",
  limit: 20,
});

GET/products/{id}

Get detailed information about a specific product.

Authentication: public key

const product = await client.products.get("prod_h7k2m");

GET/search

Simple text search across products. For advanced queries, use POST /query.

Authentication: public key

Query Parameters

qstringSearch query string (required)

categorystringFilter by category

min_pricenumberMinimum price

max_pricenumberMaximum price

in_stockbooleanOnly show in-stock items

sortstringSort: relevance, price_asc, price_desc, rating

limitnumberResults per page (default: 10)

const results = await client.search("wireless headphones", {
  maxPrice: 200,
  inStock: true,
  sort: "relevance",
});

POST/query

Unified query endpoint supporting search, recommend, compare, detail, review, and availability intents.

Authentication: public key

Request Body

intentstringRequired. One of: search, recommend, compare, detail, review, availability

querystringNatural language query (required for search)

product_idsstring[]Product IDs (for compare, detail, review, availability)

filtersQueryFiltersStructured filters (category, price, attributes, in_stock)

contextQueryContextSession context (budget, preferences, session_id, platform)

sortstringSort order

offsetnumberPagination offset (default: 0)

limitnumberResults per page (default: 10, max: 50)

const results = await client.query({
  intent: "search",
  query: "noise-cancelling headphones under $200",
  filters: {
    category: "electronics/audio/headphones",
    price: { max: 200, currency: "USD" },
    attributes: { wireless: true, noiseCancelling: true },
  },
  context: { budget: "moderate", preferences: ["comfort"] },
  limit: 5,
});

GET/recommend/{productId}

Get product recommendations based on a given product. Returns similar and complementary products.

Authentication: public key

Query Parameters

typestringRecommendation type: similar, complementary, frequently_bought_together

limitnumberNumber of recommendations (default: 5)

const recs = await client.recommend("prod_h7k2m", {
  type: "similar",
  limit: 5,
});

POST/compare

Compare multiple products side by side. Returns a structured comparison with key differences highlighted.

Authentication: public key

Request Body

product_idsstring[]Array of 2-5 product IDs to compare (required)

attributesstring[]Specific attributes to compare (optional, compares all by default)

const comparison = await client.compare({
  productIds: ["prod_h7k2m", "prod_x9y8z", "prod_a1b2c"],
  attributes: ["price", "batteryLife", "weight", "noiseCancelling"],
});

GET/reviews/{productId}

Get review data for a product including aggregated summary and individual reviews.

Authentication: public key

Query Parameters

sortstringSort: recent, helpful, rating_high, rating_low

limitnumberNumber of reviews (default: 10)

offsetnumberPagination offset

const reviews = await client.reviews.get("prod_h7k2m", {
  sort: "helpful",
  limit: 10,
});

POST/pricing

Get real-time pricing for one or more products. Returns current price, any active promotions, and volume pricing tiers.

Authentication: public key

Request Body

product_idsstring[]Product IDs to price (required)

quantitynumberQuantity for volume pricing (default: 1)

currencystringDesired currency (ISO 4217)

const pricing = await client.pricing.get({
  productIds: ["prod_h7k2m"],
  quantity: 1,
  currency: "USD",
});

POST/pricing/hold

Hold a price for a limited time while the agent completes the purchase flow. Prevents price changes during checkout.

Authentication: secret key

Request Body

product_idstringProduct to hold price for (required)

pricenumberThe price to hold (required)

currencystringCurrency (required)

duration_minutesnumberHold duration (default: 15, max: 60)

const hold = await client.pricing.hold({
  productId: "prod_h7k2m",
  price: 179.99,
  currency: "USD",
  durationMinutes: 15,
});
// hold.hold_id - use this in the transaction

POST/negotiate

Initiate or continue a price negotiation. Supports initiate, counter, accept, reject, withdraw, and inquire actions.

Authentication: secret key

Request Body

actionstringRequired. One of: initiate, counter, accept, reject, withdraw, inquire

negotiation_idstringRequired for all actions except initiate and inquire

product_idstringThe product being negotiated (required)

offered_pricenumberThe price being offered (for initiate/counter)

currencystringCurrency of the offer

quantitynumberNumber of units (default: 1)

messagestringOptional message with the offer

// Initiate negotiation
const negotiation = await client.negotiate({
  action: "initiate",
  productId: "prod_h7k2m",
  offeredPrice: 149.99,
  currency: "USD",
  message: "Comparing with competitor at $145",
});

// Accept counter-offer
await client.negotiate({
  action: "accept",
  negotiationId: negotiation.negotiation_id,
  productId: "prod_h7k2m",
});

GET/offers

List active agent-exclusive offers. These are special deals available only through AI agent channels.

Authentication: public key

const offers = await client.offers.list();

GET/offers/{id}

Get details of a specific offer.

Authentication: public key

const offer = await client.offers.get("offer_promo1");

POST/offers/{id}/claim

Claim an offer for a user. Returns a claim token to use during transaction creation.

Authentication: secret key

const claim = await client.offers.claim("offer_promo1");
// Use claim.claim_token in your transaction

GET/bundles

List available product bundles with discounted pricing.

Authentication: public key

const bundles = await client.bundles.list();

GET/bundles/{id}

Get details of a specific bundle including all products and bundle pricing.

Authentication: public key

const bundle = await client.bundles.get("bundle_audio1");

POST/transactions

Create a new transaction. Initiates the purchase flow for one or more products.

Authentication: secret key

Request Body

itemsTransactionItem[]Array of items to purchase (required)

currencystringTransaction currency (required)

shipping_addressAddressShipping address (required for physical goods)

negotiation_idstringIf this transaction results from a negotiation

offer_claim_tokenstringIf claiming an offer

escrowbooleanWhether to use escrow (default: false)

const txn = await client.transactions.create({
  items: [
    { productId: "prod_h7k2m", quantity: 1, price: 164.99 },
  ],
  currency: "USD",
  shippingAddress: {
    line1: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "94102",
    country: "US",
  },
  negotiationId: "neg_a1b2c3",
});

GET/transactions/{id}

Get the current status and details of a transaction.

Authentication: secret key

const txn = await client.transactions.get("txn_x9y8z7");

POST/transactions/{id}/confirm

Confirm a transaction and proceed to payment.

Authentication: secret key

await client.transactions.confirm("txn_x9y8z7");

POST/transactions/{id}/cancel

Cancel a transaction. Only possible before payment is completed.

Authentication: secret key

await client.transactions.cancel("txn_x9y8z7", {
  reason: "User changed their mind",
});

POST/transactions/{id}/escrow/release

Release escrowed funds to the seller. Typically called after delivery confirmation.

Authentication: secret key

await client.transactions.escrow.release("txn_x9y8z7");

POST/transactions/{id}/escrow/dispute

Open a dispute on escrowed funds. Freezes the escrow until the dispute is resolved.

Authentication: secret key

Request Body

reasonstringDispute reason (required)

evidencestringSupporting evidence or description

await client.transactions.escrow.dispute("txn_x9y8z7", {
  reason: "Product not as described",
  evidence: "Item received was a different color than listed",
});

GET/trust

Get the trust score for this storefront including overall score, tier, and individual components.

Authentication: public key

const trust = await client.trust.get();
console.log(trust.overall, trust.tier);

Example Response

JSON

{
  "overall": 92,
  "tier": "Gold",
  "components": {
    "product_accuracy": 95,
    "fulfillment_reliability": 91,
    "pricing_transparency": 94,
    "customer_satisfaction": 89,
    "response_time": 96,
    "dispute_resolution": 88,
    "data_freshness": 93
  },
  "last_updated": "2026-03-27T00:00:00Z"
}

GET/trust/compare

Compare trust scores across multiple storefronts.

Authentication: public key

Query Parameters

brand_idsstringComma-separated brand IDs to compare (required)

const comparison = await client.trust.compare([
  "brand_abc123",
  "brand_def456",
]);

POST/feedback

Submit agent feedback about the quality of product data, search results, or transaction experience.

Authentication: secret key

Request Body

typestringFeedback type: query_quality, product_accuracy, transaction_experience (required)

ratingnumberRating 1-5 (required)

query_idstringRelated query ID (if applicable)

transaction_idstringRelated transaction ID (if applicable)

commentstringFree-text feedback

await client.feedback.submit({
  type: "query_quality",
  rating: 4,
  queryId: "qry_9f8e7d6c",
  comment: "Results were relevant but missing some budget options",
});

GET/feedback/summary

Get aggregated feedback summary for this storefront.

Authentication: public key

const summary = await client.feedback.summary();

GET/health

Check storefront API health and status. No authentication required.

Authentication: public key

const health = await client.health();
// { status: "ok", latency_ms: 12, acp_version: "2.0" }

Example Response

JSON

{
  "status": "ok",
  "latency_ms": 12,
  "acp_version": "2.0",
  "timestamp": "2026-03-27T10:30:00Z"
}