Discounts & SalesCopy Anchor Link

Authors can schedule sales that temporarily reduce a circuit version's pricing. Sales are per pricing leg — each entry in a circuit's pricing array can carry its own discount percentage — and every number the API reports agrees with what a run actually bills, because both are computed by the same resolver.

How sales workCopy Anchor Link

• A sale lives on a circuit pricing row (one per circuit version). Publishing a new version copies its parent's sales to the new version's pricing row.
• Each sale window discounts specific legs of that version's pricing by a percentage (1–100). Legs are identified by the leg_id (cpl-…) stamped into the published circuit's pricing array; legacy legs fall back to their positional index ("0", "1", …).
• Whether a sale applies right now is evaluated against the window's schedule in its IANA timezone. Every read surfaces a server-computed is_active flag — it can never disagree with billing.
• Billing evaluates sales at the moment the run starts (created_at), so a flash sale applies to every run that started inside it, even if the run finished after the sale ended.
• Author awards for embedded circuits scale by the embedded circuit's own sales, not the caller's.
• Sale-priced runs are tagged SALE_<pct> (e.g. SALE_25) in wallet transactions — the web renders them as SALE 25% chips. Balance checks and elicitation confirmations are quote-adjusted automatically; x402 payment asks are always in sync.

Base URLCopy Anchor Link

All examples assume the following base URL:

https://modelworks.ai/api

AuthenticationCopy Anchor Link

Write endpoints require the circuit author's API token (or an admin/system token) sent as Authorization: Bearer YOUR_API_TOKEN. See Authentication. Public reads work anonymously but see a reduced projection, described below.

List a version's salesCopy Anchor Link

GET /circuit-pricing/{circuit_pricing_uid}/discountsCopy Anchor Link

Returns the pricing row's discount windows. The same endpoint serves two projections depending on who is asking:

Both projections include is_active on every window, evaluated with the same resolver billing uses.

curl https://modelworks.ai/api/circuit-pricing/cp-2vumrp7hq3dpfvhh7dtyvu8m/discounts

Anonymous response (sanitized projection):

{
  "status": "success",
  "status_code": 200,
  "payload": [
    {
      "kind": "ONE_TIME",
      "leg_discounts": { "cpl-t14llamq9cpbzws3y2hhffw5": 15 },
      "starts_at": "2026-11-08T19:00:00Z",
      "ends_at":   "2026-11-09T04:00:00Z",
      "valid_from": null,
      "valid_until": null,
      "recurrence_day": null,
      "window_start_time": null,
      "window_end_time": null,
      "window_timezone": "UTC",
      "is_active": true
    }
  ]
}

Active sale for a caller = filter payload on is_active == true and take, per leg, the maximum percent on offer.

Schedule a saleCopy Anchor Link

POST /circuit-pricing/{circuit_pricing_uid}/discountsCopy Anchor Link

Author or admin only. Creates a discount window on the pricing row.

Validation is end-anchored: a sale may have already started, but it must not already be over — ends_at (or valid_until) must be in the future. Overlapping windows are allowed; each leg bills at the largest discount on offer among windows active at run start.

curl -X POST https://modelworks.ai/api/circuit-pricing/cp-2vumrp7hq3dpfvhh7dtyvu8m/discounts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "RECURRING_DAILY",
    "leg_discounts": { "cpl-t14llamq9cpbzws3y2hhffw5": 25 },
    "valid_from": "2026-11-10T00:00:00Z",
    "window_start_time": "19:00:00",
    "window_end_time":   "22:00:00",
    "window_timezone": "America/Denver"
  }'

Response includes the created window's uid — keep it for updates and deletion.

Update, pause, or resume a saleCopy Anchor Link

PUT /circuit-pricing/discounts/{discount_window_uid}Copy Anchor Link

Author or admin only. Updates a window. The body carries the full window shape (all fields you created it with — partial updates are not supported). To pause a sale, send its current body with "is_enabled": false; send true to resume. Re-validation of a resumed/re-endorsed window only checks that the modified schedule is not already over.

curl -X PUT https://modelworks.ai/api/circuit-pricing/discounts/cpdw-cgyzf5h1g006kuajk33l7sce \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "ONE_TIME",
        "leg_discounts": { "cpl-t14llamq9cpbzws3y2hhffw5": 15 },
        "starts_at": "2026-11-08T19:00:00Z",
        "ends_at":   "2026-11-08T23:00:00Z",
        "window_timezone": "UTC",
        "is_enabled": false }'

Delete a saleCopy Anchor Link

DELETE /circuit-pricing/discounts/{discount_window_uid}Copy Anchor Link

Author or admin only. Permanently removes the window. Deleting a circuit pricing row (or its version) cascades to its windows.

What's on sale platform-wideCopy Anchor Link

GET /feed/active-salesCopy Anchor Link

The dashboard rail. Returns every public, non-deprecated circuit whose running version has a window active at now — at most one row per circuit — ordered by most recently scheduled.

curl "https://modelworks.ai/api/feed/active-sales?limit=3"

{
  "status": "success",
  "status_code": 200,
  "payload": {
    "sales": [
      {
        "circuit_uid": "c-d1zzwzw879lg36dfogzzk7mz",
        "circuit_name": "wandb-glm-52",
        "description": "Weights and Biases Serverless Inference powered by GLM-5.2 — a flagship MoE foundation model with 262K context.",
        "owner_username": "alice",
        "owner_avatar_url": null,
        "circuit_version_uid": "cv-bh1cbkxg3eo1zrtx",
        "percent": 15,
        "until": "2026-11-09T04:00:00Z",
        "has_one_time": true
      }
    ]
  }
}

percent is the largest leg discount for that version, and until is the soonest ending one-time window (absent for open recurring schedules). No authentication is required.

MCPCopy Anchor Link

MCP clients get the same read model through the circuit.discount.list tool (board-aware), which takes a version_uid and returns the sanitized projection with is_active per window. See Adapters for xMCP wiring.

ErrorsCopy Anchor Link