Publish Usage Limit Plan

Publish the selected draft immediately and make it the current revision.

POST /v1/projects/:project_id/usage-limit-plans/:id/publish

Authentication and scope

Requires usage_control:write. project_id is the owning project; id (when present) is its Plan ID. The API key supplies the tenant scope. Resources outside that tenant/project are not returned.

Request

There are no query parameters.

{
  "revision": 1
}

revision is a required integer of at least 1. Publish accepts only the current real draft; rollback accepts a published revision belonging to this Plan.

Response

HTTP 200.

{
  "id": "ulpv_pro_v1",
  "tenant_id": "t_001",
  "project_id": "proj_gateway",
  "plan_id": "ulp_pro",
  "name": "pro",
  "revision": 1,
  "status": "published",
  "title": "Pro daily budget",
  "description": "Default allowance",
  "published_at": 1784890000,
  "created_at": 1784889000,
  "updated_at": 1789722000,
  "rules": [
    {
      "id": "ulpr_budget_v1",
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "plan_version_id": "ulpv_pro_v1",
      "limit_key": "ulrk_budget",
      "currency": "USD",
      "measure": "amount",
      "selector_type": "all",
      "period": "day",
      "limit_amount": "100",
      "timezone": "UTC",
      "action": "block",
      "webhook_event": "usage_limit.exceeded",
      "created_at": 1784890000,
      "updated_at": 1784890000
    }
  ],
  "referenced_by_count": 0
}

Version fields: id (original version ID), tenant_id, project_id, plan_id, name, revision, status, title, optional description, original published_at (omitted for drafts), created_at, Plan updated_at, rules, and referenced_by_count. Detail/list reads can also include has_unpublished_changes and live_revision, derived from actual draft status. Reference counts are populated by detail/list reads; history and mutation responses do not calculate them. Each rule returns the business fields above plus its original id, plan_version_id, ownership, and creation/update timestamps. Empty optional fields may be omitted; timestamps are Unix seconds.

Behavior and errors

Only the actual current draft can be published and it must contain at least one rule. Archived Plans, missing drafts, or a mismatched revision return 400. Use rollback to activate historical published revisions.

If configuration committed but policy cache refresh failed, HTTP 503 returns { "error": "…", "committed": true, "version": { ... } }, containing the complete committed version. Re-read detail/current first; POST rollback to that revision retries refresh idempotently. Do not retry this publish request: the draft is already gone. Failure does not mean the database was rolled back. Do not automatically overwrite a newer current selected by another operator.

Missing/out-of-scope resources return 404, invalid inputs/lifecycle transitions 400, name/revision conflicts 409, insufficient permission 403, and internal/infrastructure failures 5xx. Failed write transactions leave Plan/history/rules unchanged; cache errors explicitly marked committed are the exception.

Lifecycle and window behavior · Create Usage Limit Plan · Get Usage Limit Plan · Update Usage Limit Plan Draft · Roll Back Usage Limit Plan · List Usage Limit Plan Revisions