Discard Usage Limit Plan Draft

Discards the unpublished draft of one Usage Limit Plan in a project. The published revision is left untouched, so the limits that subject routes already resolve keep applying.

POST /v1/projects/:project_id/usage-limit-plans/:id/discard-draft

Authentication

Requires an API key with usage_control:write.

Request

The request body is empty.

Path field	Required	Description
project_id	Yes	Project that owns the Usage Limit Plan.
id	Yes	Usage Limit Plan ID.

Response

The response is the Plan version that is visible after the discard, which is the published revision.

{
  "id": "ulpv_01J...",
  "tenant_id": "t_001",
  "project_id": "proj_gateway",
  "plan_id": "ulp_01J...",
  "name": "pro-monthly",
  "revision": 2,
  "status": "published",
  "title": "Pro monthly allowance",
  "description": "Default monthly control for Pro routes",
  "published_at": 1784890000,
  "created_at": 1784889000,
  "updated_at": 1784890100,
  "rules": [
    {
      "id": "ulpr_01J...",
      "plan_version_id": "ulpv_01J...",
      "limit_key": "monthly_tokens",
      "measure": "quantity",
      "selector_type": "unit",
      "selector_value": "tokens",
      "period": "month",
      "limit_amount": "1000000",
      "created_at": 1784889000,
      "updated_at": 1784890100
    }
  ],
  "referenced_by_count": 3
}

Field	Description
id	Plan version ID of the published revision.
plan_id	Usage Limit Plan ID.
revision	Published revision number, now the visible revision again.
status	published.
title, description	Plan metadata restored from the published revision.
published_at	Unix timestamp in seconds when this revision was published.
rules	Usage controls of the published revision, which is what routes keep resolving.
referenced_by_count	Subject routes currently bound to this Plan.

Behavior

Discarding deletes only unpublished revisions (revision greater than the published revision) together with their usage controls. The published revision, its usage controls, and the published revision history are not modified, so no realtime limit state changes: active subject routes, realtime limit accumulators, historical usage, wallet balances, and ledger records are all untouched.

Deletion is determined by actual status=draft, never revision ordering. After v3 rolls back to v1, discarding draft v4 preserves v2/v3 and their rules. The next edit allocates the highest remaining historical revision + 1; discarded, never-published draft numbers can be reused.

Plan-level title and description revert to the values of the published revision.

Errors

Error message	Cause
no draft revision to discard	The visible revision is already the published revision.
a plan without a published revision has no draft to discard	The Plan was never published, so there is no live revision to revert to.
archived usage limit plan has no draft to discard	The Plan is archived. Restore it first to publish or discard its draft.

Use List Usage Limit Plans to check revision, live_revision, and has_unpublished_changes before discarding. Use Restore Usage Limit Plan to make an archived Plan editable again.

Archive/restore and draft discard preserve the selected live pointer; they never reactivate the highest historical published revision. Draft and live retain their own metadata.

Rollback endpoint · Lifecycle and window behavior