REST API reference

The Build Me Web REST API lets you automate sites, commerce, and analytics from your own systems. This reference covers authentication, core site resources, commerce endpoints, pagination conventions, and error handling. Base URL: https://api.buildmeweb.example/v1.

Authentication

Create an API key in workspace settings under Developers API keys. Send it as a Bearer token on every request. Rotate keys regularly and scope them to the minimum resources needed (sites read, commerce write, analytics read, and so on).

Never embed secret keys in client-side JavaScript. Use server-to-server calls or short-lived tokens minted by your backend. In CI, store keys as secrets and mask them in logs.

curl -s https://api.buildmeweb.example/v1/sites \
  -H "Authorization: Bearer $BMW_API_KEY" \
  -H "Accept: application/json"

Optional headers: X-Request-ID for tracing (we echo it in responses), Idempotency-Key for unsafe retries on create endpoints. Keys should be unique per logical operation.

• TLS 1.2+ required.
• JSON request bodies with Content-Type: application/json.
• UTC timestamps in ISO-8601.
• Rate limits returned via X-RateLimit-* headers.

Sites

GET /v1/sites lists sites you can access. GET /v1/sites/:id returns domain, publish status, default locale, and environment metadata. POST /v1/sites/:id/publish queues a publish when your key has write scope.

GET /v1/sites?limit=50&cursor=eyJvZmZzZXQiOjUwfQ
{
  "data": [
    {
      "id": "site_123",
      "name": "Northwind marketing",
      "primaryDomain": "www.northwind.example",
      "publishStatus": "published",
      "updatedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "nextCursor": null
}

Domains: GET /v1/sites/:id/domains lists hostnames and certificate states. Triggering DNS verification is available via POST /v1/sites/:id/domains/:domainId/verify.

Content: page listing endpoints return slugs and updated times for synchronization with external CMS workflows. Mutating page bodies via API is available on plans that enable headless content writes — validate payloads against the section schema to avoid publish failures.

1. List sites and select the target id.
2. Confirm domain and publish status before automation.
3. Publish only after preview checks in your pipeline pass.
4. Store returned publish job IDs for status polling.

Commerce

Manage products and orders under /v1/stores/:storeId/.... List products with GET /products, upsert with PUT /products/:sku, and fetch orders with GET /orders. Idempotency keys are required for create-order style mutations and recommended for inventory adjustments.

POST /v1/stores/store_01/products
Idempotency-Key: create-sku-TR-8-SLT
{
  "title": "Trail Runner",
  "sku": "TR-8-SLT",
  "price": { "amount": "129.00", "currency": "USD" },
  "inventory": { "tracked": true, "quantity": 40 }
}

Orders include line items, totals, fulfillment state, and customer references. Refunds: POST /orders/:id/refunds with amount and optional restock flag. Always verify payment provider state if you orchestrate refunds outside the Admin UI.

Webhooks complement polling — subscribe to order.completed rather than hammering GET /orders every minute. See Webhooks & events for signatures.

• Pagination: cursor-based; do not assume stable offsets under high write load.
• Filtering: status, updated_since, and sku where documented.
• Expand: optional expand=customer,line_items on supported order GETs.

Errors

Errors return JSON with code, message, and optional details array for field issues. Respect 429 rate limits with exponential backoff and jitter. Treat 409 as a signal to fetch current state before retrying conflicting updates.

{
  "error": {
    "code": "validation_failed",
    "message": "Product SKU already exists",
    "details": [{ "field": "sku", "issue": "duplicate" }]
  }
}

Common status codes: 400 validation, 401 missing/invalid auth, 403 insufficient scope, 404 unknown resource, 409 conflict, 422 semantic validation, 429 rate limited, 5xx retry with backoff.

• API key scoped and stored in a vault
• Idempotency-Key on creates
• Backoff implemented for 429/5xx
• Request IDs logged for support escalations

Pagination & versioning

List endpoints return data plus nextCursor. Pass the cursor as cursor on the next call until null. The /v1 prefix is stable; backwards-incompatible changes ship under a new major version with advance notice in the developer changelog.

Best practices

Automate least privilege. Prefer webhooks to polling. Validate responses even on 200 — partial success shapes can appear on batch endpoints. In sandboxes, exercise failure paths (duplicate SKU, insufficient inventory) so production handlers exist before Black Friday. Pair this reference with the CLI for deploy automation and Webhooks for event-driven systems.

Prerequisites & preparation

Before changing production settings for the REST API, align the people who own content, DNS, analytics, and approvals. A fifteen-minute kickoff that names owners prevents multi-day Slack archaeology later. Capture decisions in the workspace notes so the next teammate inherits context instead of guesswork.

Gather credentials and access: workspace admin or editor role, DNS control when hostnames are involved, payment or API sandbox accounts when money paths are involved, and a shared checklist link. Confirm which environment you will rehearse in — preview first, production only after a green run.

Create scoped keys for staging and production; choose a language HTTP client with timeout and retry support.

Detailed walkthrough

Work the happy path slowly the first time. Narrate what you expect to see after each click: a status badge, a DNS record, a webhook delivery, a Lighthouse metric. When reality diverges, stop and resolve the mismatch instead of clicking ahead — most outages begin as ignored yellow states.

1. Authenticate with Bearer tokens; send X-Request-ID on writes.
2. List sites; confirm IDs before automation.
3. Exercise commerce product upsert with Idempotency-Key.
4. Handle 429 with exponential backoff and jitter.
5. Prefer webhooks over tight polling loops for orders and publishes.

Worked example:

Authorization: Bearer $BMW_API_KEY
Idempotency-Key: create-sku-TR-8-SLT
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

Edge cases & failure modes

Plan for partial failure. Networks drop, registrars delay, providers rate-limit, and humans approve the wrong revision. Your runbook should say what “abort” looks like: leave preview up, roll back the release, or freeze campaigns until metrics recover.

• Client-side exposure of secret API keys.
• Retries without idempotency creating duplicate products/orders.
• Parsing re-serialized JSON before HMAC on related webhook flows.

QA checklist before you announce

• Happy path verified on mobile and desktop
• Failure path messaging reviewed
• Owners named for the first hour after launch
• Rollback or freeze path documented

Operating the change

After launch, watch the metrics that prove the change worked — not vanity charts. Pair quantitative signals with one qualitative check (support ticket themes, sales feedback). Schedule a follow-up within a week to remove temporary flags, raise DNS TTLs, or archive the experiment.

Rotate keys on a schedule; log request IDs for support escalations.

Least privilege scopes limit blast radius when a CI token leaks.

Cursor pagination is safer under high write load than naive offsets.

Validate 200 responses on batch endpoints — partial success shapes exist.

Versioning under /v1 stays stable; watch the developer changelog for majors.

Sandbox should exercise conflict and validation errors, not only happy paths.

Pair API automation with CLI deploys and webhook consumers for end-to-end ops.

Never print tokens in CI logs; mask secrets in your pipeline configuration.

Store publish job IDs when queueing site publishes so you can poll status without guesswork.

Implementation checklist

Confirm scoped API keys per environment on preview before you promote. Name who approves the change, which environment is authoritative, and what “done” looks like in measurable terms.

Document Idempotency-Key on create mutations where the team already looks — workspace notes or the engineering handbook — not only in a meeting memory.

Rehearse cursor pagination under write load against written acceptance checks. If you cannot name the verification event (order, DNS lookup, deploy health, or signed API call), you are not ready to announce.

Measure 429 backoff with jitter with anonymized but realistic data, and keep logs, headers, or screenshots for at least one release cycle so regressions have a baseline.

Operating it with your team

Automate request ID logging for support so the next teammate can repeat the path without tribal knowledge. Prefer vaulted secrets over chat paste, and archive temporary exceptions with an end date.

Review webhook preference over tight polling when two tools disagree. Pick a source of truth in advance so incidents do not burn the rollback window debating dashboards.

Validate sandbox exercises for conflict errors before paid traffic or customer emails amplify mistakes. Capture request IDs or screenshots for support if anything looks off.

When you finish this guide, you should be able to explain the happy path, the abort path, and the metrics that prove success. If any of those are fuzzy, revisit the walkthrough with your teammates before you scale traffic, spend, or automation.