cresvadevelopers

API Reference

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

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://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");
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"
}