Skip to content

Revert Rule Revision

Method

This API follows the REST methodology.

HTTP Method

POST: Pin an existing design-rule revision as the project's active one.

Revisions are immutable and nothing is ever rolled back or deleted. A revert moves a pointer: it sets the active-revision pointer the worker honours, so the next generation pins the chosen revision instead of the newest one.

Naming Convention

The request body uses camelCase. The response is proxied verbatim from the internal wf2des-api data plane, so its fields are snake_case.

Request and Response

Headers

Request Headers

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

Response Headers

  • Content-Type

Revert Rule

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/rules/revert

Path Parameters

Name Type Required Description
organization_id integer Required Organization ID
project_id integer Required Project ID

Request Body

The request body is JSON.

{
  "designRuleId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e6f",
  "version": 3
}

Request Parameters

Name Type Required Description
designRuleId string Required The design_rule_id whose revision to pin.
version integer Required The revision version to make active. Positive integer.

The pair must identify an existing revision โ€” see GET โ€ฆ/wf2des/rules/revisions for the list to choose from.

Response

The response is JSON (HTTP status: 200 OK) โ€” the now-active revision's summary, in the same shape GET โ€ฆ/wf2des/rules/latest returns.

{
  "design_rule_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e6f",
  "version": 3,
  "content_hash": "b1946ac92492d2347c6235b4d2611184",
  "draft_source": "llm_extracted",
  "extracted_at": "2026-07-28T11:02:00Z",
  "processed_at": "2026-07-28T11:02:06Z"
}

Response Fields

Name Type Description
design_rule_id string | null The lineage the now-active revision belongs to.
version integer | null The version that is now active.
content_hash string | null Hash over that revision's merged ruleset.
draft_source string | null How the revision was produced.
extracted_at string | null When extraction ran.
processed_at string | null When the revision was landed.

Interaction with a new upload

A revert is not permanent. Uploading guideline boards through POST โ€ฆ/wf2des/rules clears the pointer, because a fresh upload is a deliberate "this is now current". After an upload the newest revision is active again, whatever was pinned before.

Reverting is idempotent: pinning the revision that is already active returns 200 with the same summary.

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito. The caller must additionally hold Write access to the project.

Error Handling

Description Status Code Status Name
Invalid body (designRuleId absent/empty, version absent or not a positive integer) 400 Bad Request
Missing authentication credentials 401 Unauthorized
Insufficient permissions (no Write access to the project) 403 Forbidden
No revision exists for the given (designRuleId, version) pair 404 Not Found
Upstream write failure (wf2des-api) 500 Internal Server Error

Processing Flow

  1. Extract organization ID and project ID from path parameters; extract designRuleId and version from the request body.
  2. Verify the user has Write access to the project.
  3. Proxy the write to the internal wf2des-api data plane (X-AI-Service-Token), scoped to the organization and project.
  4. The data plane verifies the target (design_rule_id, version) revision exists; when it does not, the call returns 404 and no pointer is written.
  5. It upserts the mutable active-pointer document that the worker's rule resolution honours.
  6. Return the now-active revision's summary.

The target revision itself is never modified โ€” only the pointer changes, which is what keeps the revision history a true audit trail.