Developers

API Reference

ValyuPeak exposes a REST API so you can sync your product catalog, manage webhooks, and read the blog feed programmatically. Base URL: https://valyupeak.com

Authentication

The ValyuPeak API uses two authentication schemes depending on the endpoint.

API KeyBearer token

Used for machine-to-machine integrations. Generate a key in Dashboard → Settings → Integrations. Pass it in the Authorization header.

Authorization: Bearer vp_live_abc123...

Session CookieClerk session

Used when calling the API from a signed-in browser context. The Clerk session cookie is automatically sent by the browser — no extra setup required.

Cookie: __session=<clerk_token>

⚠API keys grant full access to your workspace data. Never expose them in client-side code or public repositories. Rotate compromised keys immediately in Dashboard → Settings → Integrations.

Catalog Products

Read and update your catalog products. Useful for syncing prices from your own ERP or inventory system into ValyuPeak so the repricing engine always has your latest cost data.

All /api/v1/internal-products endpoints require API Key authentication.

GET/api/v1/internal-productsAPI Key

Returns all catalog products in the workspace associated with the API key. Optionally filter by SKU.

Query parameters

Param	Type	Required	Description
sku	string	No	Filter results to the product with this exact SKU.

Response

{
  "success": true,
  "count": 2,
  "products": [
    {
      "id": "clxyz...",
      "name": "Wireless Earbuds Pro",
      "sku": "WEP-001",
      "price": 79.99,
      "minPrice": 49.99,
      "url": "https://yourstore.com/products/wep-001",
      "category": { "id": "...", "name": "Electronics" },
      "productMatches": [
        {
          "isRepricingEnabled": true,
          "trackedProduct": {
            "name": "Competitor Earbuds",
            "currentPrice": 74.99
          }
        }
      ]
    }
  ]
}

PATCH/api/v1/internal-productsAPI Key

Update the price and/or minimum price floor for a product identified by SKU. Use this to push cost or list-price changes from your ERP into ValyuPeak so the repricing engine recalculates correctly.

Request body (JSON)

Field	Type	Required	Description
sku	string	Yes	The SKU of the product to update.
price	number	No	New current / list price.
minPrice	number	No	New minimum price floor. The repricing engine will never go below this value.

Response

{
  "success": true,
  "product": {
    "id": "clxyz...",
    "sku": "WEP-001",
    "price": 84.99,
    "minPrice": 52.00,
    ...
  }
}

At least one of price or minPrice must be present. SKU matching is case-sensitive.

Webhooks

Register HTTPS endpoints to receive real-time event notifications — price changes, stock alerts, and repricing actions — as they happen.

Webhook management endpoints require Session Cookie authentication (signed-in user). Events are delivered to your registered URL using API Key authentication — see the Webhook Events section for the payload schema.

GET/api/v1/webhooksSession

Returns all webhook endpoints registered for the specified workspace.

Query parameters

Param	Type	Required	Description
workspaceId	string	Yes	The ID of the workspace whose webhook endpoints to list.

Response

{
  "success": true,
  "endpoints": [
    {
      "id": "clxyz...",
      "url": "https://yourserver.com/hooks/valyupeak",
      "isActive": true,
      "workspaceId": "...",
      "createdAt": "2025-06-01T10:00:00.000Z"
    }
  ]
}

POST/api/v1/webhooksSession

Register a new webhook endpoint for a workspace. A random 64-character HMAC secret is generated and returned once — store it securely, as it cannot be retrieved afterwards.

Request body (JSON)

Field	Type	Required	Description
workspaceId	string	Yes	The workspace this webhook belongs to.
url	string	Yes	Your HTTPS endpoint URL. Must be publicly reachable.
isActive	boolean	No	Whether to start delivering events immediately. Defaults to true.

Response

{
  "success": true,
  "endpoint": {
    "id": "clxyz...",
    "url": "https://yourserver.com/hooks/valyupeak",
    "secret": "a3f8e2c1d4b7...",
    "isActive": true,
    "workspaceId": "..."
  }
}

The secret field is only returned on creation. Use it to verify the X-ValyuPeak-Signature header on incoming events.

Blog Feed

A public JSON feed of all ValyuPeak blog posts. No authentication required. Intended for AI agents, RSS readers, and integrations that want to embed our content.

GET/api/v1/blogPublic

Returns a JSON array of all published blog posts, sorted by date descending. Includes full metadata: title, slug, description, tags, author, cover image, and published date.

Response

{
  "posts": [
    {
      "slug": "how-to-beat-competitors-on-price",
      "title": "How to Beat Competitors on Price Without a Race to the Bottom",
      "description": "A practical guide to intelligent repricing...",
      "date": "2025-05-15",
      "author": "valyupeak-team",
      "tags": ["repricing", "strategy"],
      "coverImage": "/blog/covers/repricing-guide.jpg",
      "readingTime": "6 min read"
    }
  ]
}

This endpoint is explicitly allowed in robots.txt for AI crawlers (ClaudeBot, GPTBot, PerplexityBot).

Webhook Event Reference

All events are delivered as HTTP POST requests to your registered endpoint with the following envelope structure. Verify authenticity using the HMAC signature.

Envelope

POST https://yourserver.com/hooks/valyupeak
Content-Type: application/json
X-ValyuPeak-Signature: <hmac-sha256-hex>

{
  "id": "evt_1748000000000_abc123",
  "type": "price.changed",
  "created": "2025-06-01T14:32:00.000Z",
  "data": { ... }
}

Signature verification (Node.js example)

import { createHmac } from "crypto";

function isValidSignature(body: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return expected === signature;
}

// In your route handler:
const rawBody = await request.text();
const sig     = request.headers.get("x-valyupeak-signature") ?? "";
if (!isValidSignature(rawBody, sig, process.env.VALYUPEAK_WEBHOOK_SECRET!)) {
  return new Response("Forbidden", { status: 403 });
}

Event types

Event type	Triggered when
price.changed	A tracked product's price changes above your configured threshold
stock.out	A tracked product goes out of stock
stock.recovered	A previously out-of-stock product becomes available again
promo.changed	A competitor's promotional text appears, changes, or disappears
url.broken	A tracked product URL returns 404 / becomes unreachable
url.recovered	A previously broken URL becomes reachable again
schema.improved	A competitor's schema score increases by 10+ points
gtin.added	A competitor adds a GTIN/barcode to a product listing
description.changed	A competitor updates their product description
listing.changed	A competitor adds or removes product images

Rate Limits

To maintain reliability for all users, the API enforces the following limits:

Endpoint group	Limit
/api/v1/internal-products (read)	120 requests / minute
/api/v1/internal-products (write)	30 requests / minute
/api/v1/webhooks	60 requests / minute
/api/v1/blog	Unlimited (public, cached)

Rate-limited responses return HTTP 429 Too Many Requests. If you need higher limits for a specific integration, contact hello@valyupeak.com.

← Back to ValyuPeak