RulesService

Read the rules this project runs under, in the same words the console shows them in, and propose a change to them. Proposing writes nothing: it files a proposal that lands in the project's inbox, and a person approves or declines it there. That boundary is the point rather than a limitation, and it is the same one the approval gate draws around a parked call.

Every call is a POST to https://api.atmon.ai/automaton.v1.RulesService/<Call> with a JSON body, and authenticates with Authorization: Bearer <your project key>. Field names in JSON are lowerCamelCase, so the field written tool_slug below is toolSlug on the wire. How to call the API has the whole convention.

Calls

GetRules

Reads the project's rules in plain words, grouped by what each one governs. An empty answer at version 0 means no rules have ever been written.

Request GetRulesRequest, response GetRulesResponse.

POST /automaton.v1.RulesService/GetRules HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{}

The response:

{
  "version": 0,
  "rules": [{
    "area": "...",
    "text": "..."
  }]
}

ProposeRulesChange

Files a proposed change to the rules. It writes no policy: the answer is a proposal id in the PENDING state, and a person approves or declines it in the console. Refiling an identical pending proposal answers with the one already filed. A project may file a small number of proposals per hour; past that the call is refused with resource_exhausted.

Request ProposeRulesChangeRequest, response ProposeRulesChangeResponse.

POST /automaton.v1.RulesService/ProposeRulesChange HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "changes": [{
    "setSpendCeiling": { ... },
    "requireApproval": { ... },
    "setAllowedTools": { ... }
  }],
  "reason": "..."
}

The response:

{
  "proposal": {
    "id": "...",
    "changes": [{ ... }],
    "reason": "...",
    "effects": ["..."],
    "state": "RULE_PROPOSAL_STATE_PENDING",
    "note": "...",
    "createdAt": "2026-01-31T09:15:00Z",
    "decidedAt": "2026-01-31T09:15:00Z",
    "appliedPolicyVersion": 0
  },
  "deduplicated": true
}

GetRuleProposal

Reads one filed proposal in any state, so a caller can wait for the decision and report it. A declined proposal reads as declined with whatever the decider wrote; do not file it again.

Request GetRuleProposalRequest, response GetRuleProposalResponse.

POST /automaton.v1.RulesService/GetRuleProposal HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "id": "..."
}

The response:

{
  "proposal": {
    "id": "...",
    "changes": [{ ... }],
    "reason": "...",
    "effects": ["..."],
    "state": "RULE_PROPOSAL_STATE_PENDING",
    "note": "...",
    "createdAt": "2026-01-31T09:15:00Z",
    "decidedAt": "2026-01-31T09:15:00Z",
    "appliedPolicyVersion": 0
  }
}

Messages

GetRuleProposalRequest

GetRuleProposalResponse

GetRulesRequest

No fields. The call takes its scope from the authenticated project.

GetRulesResponse

ProposeRulesChangeRequest

ProposeRulesChangeResponse

RequireApproval

RequireApproval proposes adding calls to the approval gate. It only ever adds: a proposal cannot take a tool out of the gate, because loosening the gate through the surface an agent writes to would make the gate advisory. Removing one is a console edit by a person.

RuleProposal

RuleProposal is one filed change and everything decided about it.

RuleStatement

Rules as an agent reads them, and proposes changes to.

The document above is written for the code that enforces it. An assistant asked "what are the rules here" needs the same facts in the language the person who wrote them used, and an assistant that spots a missing ceiling needs somewhere to say so. Neither of those is a policy write: the asker is never the approver, so a change an agent drafts becomes a proposal that lands beside the approvals in the project's inbox, and a person decides it.

RuleStatement is one rule in force, written the way the console shows it rather than the way the document stores it.

RulesChange

RulesChange is one edit to the project's rules. Exactly one field is set, and a change carrying none or more than one is refused when it is filed rather than stored as something nobody can apply. A proposal that wants two edits carries two of these.

Three fields rather than a oneof: on the JSON wire the two are written identically, and the rule is enforced at the desk either way, with a message naming the field and what to send instead.

SetAllowedTools

SetAllowedTools proposes narrowing what may run to a named list. An empty list on either field leaves that list alone; the document's own convention is that an empty allow list allows everything, so clearing one is a loosening and is not proposable here.

SetSpendCeiling

SetSpendCeiling proposes one ceiling. A ceiling for the same scope, window, entity and toolkit replaces the one in force; a new combination is added. A proposal setting every dimension to zero removes the ceiling, which is a loosening and reads that way in the proposal's own words.

Enums

BudgetScope

BudgetScope is whose spending a ceiling counts, following VelocityLimit's scopes minus the tool scope: money is spent by a project or by one of its entities, and a per-tool ceiling would be a quota, which max_provider_calls already expresses.

BudgetWindow

BudgetWindow is the period a ceiling applies over, evaluated in UTC. TOTAL never resets, so only raising the ceiling releases what it parked; DAILY and MONTHLY reset at the UTC boundary and release a parked job with no operator action.

RuleProposalState