Get the ordered writing-rule set (precedence ladder applied)

GET

/v1/rules

• Production
• Local

Return the ORDERED active rule list with the deterministic §7 precedence ladder applied SERVER-SIDE (NO LLM on our side): hard before soft; specificity per-agent > category > general/house-style; human before agent; newest rev/created_at; higher priority. Includes the general/house-style layer (D2) IN ADDITION to the named category’s rules, plus a soft return cap (≈25/category + 25 general, dropping the least-specific general first). The agent reconciles the ordered list semantically; we never apply a rule. Rules are CUSTOMER-scoped and agent-attributed (the cross-agent exception).

Authorizations

• AgentKey
  mailbox:read

Parameters

Query Parameters

category_id

string

Category id (cat_…). Empty returns ONLY the house-style/general layer.

scope

string

Allowed values: general category

Narrow to one layer (general | category). Default returns both.

Responses

200

Ok

The ORDERED active rule set (the §7 precedence ladder applied SERVER-SIDE, capped). Category rules precede general/house-style rules; within each, highest precedence first. The agent reconciles the list semantically (NO LLM on our side).

object

items

required

Array<object>

A learned writing rule (rule_…) in the Review Loop (D2/D11). House-style/ general (scope=‘general’, applies across all categories) or category-scoped. Append-only by supersession: an edit is a new rev (same lineage_id) with the prior flipped to superseded. Read by the agent at compose/redraft time via the ordered get_rules ladder; we never apply it. Opaque ids only (D10).

object

id

required

Opaque rule id (rule_…).

string

rule_layer

Ownership layer (org/project model). org = house-style inherited by every project in the org; project = layered on top (the agent-plane default). Project/per-agent rules outrank broader org rules in the ordered get_rules ladder.

string

Allowed values: org project

org_id

The org this rule belongs to.

string

project_id

The project this rule belongs to; empty for an org-layer rule.

string

lineage_id

required

Stable lineage handle across versions (rln_…).

string

rev

required

integer

scope

required

General = house-style (D2).

string

Allowed values: general category

category_id

Set iff scope=category (cat_…).

string

scope_agent_id

Set for a per-agent override; empty = all org agents.

string

rule_text

required

string

kind

required

Hard = non-overridable.

string

Allowed values: soft hard

priority

required

integer

status

required

string

Allowed values: proposed active superseded retired

supersedes_id

The prior rev this row superseded (rule_…).

string

author_kind

required

string

Allowed values: agent human

created_at

required

string format: date-time

updated_at

required

string format: date-time

total

required

integer

house_style_version

integer

category_rules_version

integer

rule_high_water

integer

composition_token

Opaque short-lived proof of this exact effective rules snapshot. Omitted on filtered scope queries.

string

composition_token_expires_at

string format: date-time

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope