API Reference

The CommerceOps Hub REST API lets you validate, clean, and query e-commerce data programmatically. Integrate data quality checks directly into your pipeline, CI/CD, or ERP system.

Authentication

All API requests require an X-API-Key header. Generate your API key in the Integrations tab after upgrading.

copy# Include in every request
X-API-Key: coh_your_key_here

# Or use Bearer token
Authorization: Bearer coh_your_key_here

Error Codes

Rate Limits

Upload endpoints: 10 requests / minute. All other endpoints: 60 requests / minute. Rate limit headers are included in every response:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1716300060

List Jobs

copy[
  {
    "id": "3f8a2b1c-...",
    "filename": "products_may.csv",
    "status": "done",
    "check_types": "product",
    "rows_total": 1240,
    "rows_error": 23,
    "rows_warning": 87,
    "rows_fixed": 41,
    "health_score": 78,
    "created_at": "2026-05-22T10:30:00.000Z"
  }
]

Get Job Details

copy{
  "id": "3f8a2b1c-...",
  "filename": "products_may.csv",
  "status": "done",
  "health_score": 78,
  "issues": [
    {
      "id": 1,
      "issue_row": 5,
      "severity": "error",
      "field": "price",
      "code": "INVALID_PRICE",
      "message": "Price must be a positive number",
      "original_value": "abc",
      "fixed_value": null
    }
  ]
}

Validate Records

copycurl -X POST https://hub.corestackapi.com/v1/validate \
  -H "X-API-Key: coh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "SKU": "PRD-001", "Name": "Blue T-Shirt", "Price": "590" },
      { "SKU": "",       "Name": "Red Jeans",  "Price": "abc" }
    ],
    "mapping": { "sku": "SKU", "title": "Name", "price": "Price" },
    "check_types": "product,price"
  }'

copy{
  "stats": {
    "rows": 2,
    "errors": 2,
    "warnings": 0,
    "fixes": 0,
    "score": 60
  },
  "issues": [
    { "row": 2, "severity": "error", "field": "sku", "code": "MISSING_SKU", "message": "SKU is required" },
    { "row": 2, "severity": "error", "field": "price", "code": "INVALID_PRICE", "message": "Price must be a positive number" }
  ],
  "cleaned": [/* auto-fixed rows */]
}

Webhooks Overview

Webhooks push real-time events to your endpoint when jobs complete. Configure them in the Integrations → Webhooks section.

Webhook Payload

copy{
  "event": "job.complete",
  "timestamp": "2026-05-22T10:30:00.000Z",
  "jobId": "3f8a2b1c-...",
  "filename": "products_may.csv",
  "rows": 1240,
  "stats": {
    "errors": 23,
    "warnings": 87,
    "fixes": 41,
    "score": 78
  }
}

Signature Verification

If you set a webhook secret, every request includes an X-CommerceOps-Signature header with an HMAC-SHA256 signature.

copy# Node.js verification example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Check Types Reference

Standard Field Names

Use these semantic field names in your mapping object. Each maps to the column name in your data.

Platform Templates

Pass a platform value to apply platform-specific validation rules (title length, required fields, image specs).