API Reference

Documentation

Run evidence-backed merchant audits and generate downloadable fix assets programmatically. No authentication required.

Base URL

Use this deployment origin for API requests:

https://www.merchantsignals.com

Utility routes: /api/health · /openapi.json

GET/api/health

Health check

Returns service status, version, timestamp, and whether Upstash Redis is configured.

Request

Content-Type: application/json

No request body.

Response

Success: 200 OK · Error: 400 / 500

{
  "status": "ok",
  "service": "commerce-optimizer",
  "version": "3.3.1",
  "timestamp": "2026-05-30T12:00:00.000Z",
  "redis": "configured"
}

curl

curl -s https://www.merchantsignals.com/api/health

OpenAPI specification

Machine-readable API description for health, audit, and generate-fixes endpoints.

https://www.merchantsignals.com/openapi.json

POST/api/audit

Run audit

Crawls a merchant URL and returns platform analysis, evidence-backed findings grouped by status, and cache metadata. Findings are derived only from crawled pages and discovery files.

Request

Content-Type: application/json

{
  "url": "https://www.allbirds.com"
}

Response

Success: 200 OK · Error: 400 / 500

{
  "url": "https://www.allbirds.com/",
  "crawledAt": "2026-05-30T12:00:00.000Z",
  "platform": {
    "platform": "Shopify",
    "confidence": "high",
    "evidence": ["Shopify CDN asset detected"],
    "sourceUrls": ["https://www.allbirds.com/"]
  },
  "findings": [
    {
      "id": "product-pages",
      "label": "Product pages",
      "status": "detected",
      "confidence": "high",
      "evidence": "URL pattern match on crawled pages",
      "evidenceUrls": ["https://www.allbirds.com/products/example"],
      "sourceUrl": "https://www.allbirds.com/products/example",
      "discoveredFromUrl": null
    }
  ],
  "grouped": {
    "detected": [],
    "missing": [],
    "needsReview": []
  },
  "cacheStatus": "MISS",
  "expiresAt": "2026-05-30T14:00:00.000Z"
}

curl

curl -s -X POST https://www.merchantsignals.com/api/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.allbirds.com"}'

POST/api/generate-fixes

Generate fixes

Reuses the audit crawl and cache, then returns six downloadable assets built only from crawled evidence. TODO placeholders mark missing facts — nothing is invented.

Request

Content-Type: application/json

{
  "url": "https://www.allbirds.com"
}

Response

Success: 200 OK · Error: 400 / 500

{
  "auditedUrl": "https://www.allbirds.com/",
  "generatedAt": "2026-05-30T12:05:00.000Z",
  "cacheStatus": "HIT",
  "assets": [
    {
      "filename": "llms.txt",
      "contentType": "text/plain",
      "content": "# Allbirds\n> TODO: Add merchant description\n..."
    },
    {
      "filename": "merchant-profile.md",
      "contentType": "text/markdown",
      "content": "# Merchant Profile\n..."
    },
    {
      "filename": "organization-schema.json",
      "contentType": "application/json",
      "content": "{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"Organization\"\n}\n"
    },
    {
      "filename": "product-schema-template.json",
      "contentType": "application/json",
      "content": "{\n  \"@type\": \"Product\"\n}\n"
    },
    {
      "filename": "faq-schema-template.json",
      "contentType": "application/json",
      "content": "{\n  \"@type\": \"FAQPage\"\n}\n"
    },
    {
      "filename": "agent-commerce-readiness.md",
      "contentType": "text/markdown",
      "content": "# Agent Commerce Readiness\n..."
    }
  ]
}

curl

curl -s -X POST https://www.merchantsignals.com/api/generate-fixes \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.allbirds.com"}'

Error responses

Invalid requests return 400 with { "error": "..." }. Server failures return 500 with the same shape.

{
  "error": "Enter a valid website URL"
}

← Back to audit