Observability

Add an overview of the Observability API here. This block is preserved across regenerations.

Endpoints

GET /api/v1/error-codes

Stable error code catalog. Returns every error code the v1 API can return, its HTTP status, description, and whether the error is retryable.

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/error-codes

Responses

200

Complete error code catalog

application/json

Catalog of all stable v1 API error codes. Every error response from /api/v1 includes a code field that matches one of these entries. Use retryable to decide whether to back off and retry.

get/error-codes

HTTPcURLJavaScriptPython

GET /api/v1/error-codes HTTP/1.1
Host: peakcommerce.app
Accept: */*

200

Complete error code catalog

{
  "codes": [
    {
      "code": "rate_limit_exceeded",
      "description": "text",
      "retryable": true
    }
  ]
}

Notes, examples, or caveats for GET /error-codes go here.

GET /api/v1/status

Component-level health status suitable for status-page consumption. No auth required. Cached for 30 seconds.

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/status

Responses

200

Component health status (may be operational, degraded, or incident)

application/json

statusstring · enumRequired

Worst-case status across all components

Possible values:

cachedAtstring · date-timeRequired

When this status snapshot was computed (TTL: 30 s)

get/status

HTTPcURLJavaScriptPython

GET /api/v1/status HTTP/1.1
Host: peakcommerce.app
Accept: */*

200

Component health status (may be operational, degraded, or incident)

{
  "status": "operational",
  "components": [
    {
      "name": "database",
      "status": "operational",
      "latencyMs": 1,
      "detail": "text"
    }
  ],
  "cachedAt": "2026-07-14T00:10:11.115Z"
}

This endpoint is public and unauthenticated, so each component reports only subsystem reachability — operational when the dependency is reachable, degraded/incident otherwise. It deliberately does not expose any tenant-specific detail (integration names or types, per-tenant catalog-sync state, or active-webhook counts); those are cross-tenant data and are only available through authenticated, tenant-scoped endpoints.

GET /api/v1/usage

Per-key API usage metrics (admin scope). Returns request counts, error counts, rate-limit hits, and latency broken down by route and 1-minute time bucket.

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/usage

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Query parameters

fromstring · date-timeOptional

Start of the time window (ISO 8601). Defaults to 24 hours ago.

tostring · date-timeOptional

End of the time window (ISO 8601). Defaults to now.

apiKeyIdstringOptional

API key ID to filter. Defaults to the calling key. Pass * to see all keys on the tenant.

routestringOptional

Filter to a specific route pattern (e.g. /accounts/:id).

Responses

200

Usage summary with per-route and per-bucket breakdowns

application/json

Per-key API usage metrics aggregated by route and time bucket

401

API key required

application/json

403

Insufficient scope (admin required)

application/json

get/usage

HTTPcURLJavaScriptPython

GET /api/v1/usage HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "summary": {
    "totalRequests": 1,
    "totalErrors": 1,
    "totalRateLimited": 1,
    "avgLatencyMs": 1,
    "errorRate": 1
  },
  "byRoute": [
    {
      "route": "/accounts/:id",
      "method": "GET",
      "requests": 1,
      "errors": 1,
      "rateLimited": 1,
      "avgLatencyMs": 1
    }
  ],
  "byBucket": [
    {
      "timeBucket": "2026-07-14T00:10:11.115Z",
      "requests": 1,
      "errors": 1,
      "rateLimited": 1,
      "avgLatencyMs": 1
    }
  ],
  "window": {
    "from": "2026-07-14T00:10:11.115Z",
    "to": "2026-07-14T00:10:11.115Z",
    "granularity": "minute"
  },
  "apiKey": {
    "id": "text",
    "prefix": "text",
    "name": "text"
  }
}

Notes, examples, or caveats for GET /usage go here.