Atomically replace the organisation's rule stack. Entries are processed in list order — index 0 compiles first. At most one entry may carry `is_entity_default=true`. Every assistant in the organisation has its rule cache invalidated after the operation.

## Path parameters

**`org_id`** string required

Organisation ID (prefixed with `org_`).

## Body parameters

**`entries`** array optional

List of stack entries (max 50). Omitting or sending an empty list clears the stack. Each entry is an object with:

- **`rule_id`** string required — Rule ID to include in the stack (prefixed with `rule_`).
- **`priority`** integer optional — Attachment priority (0–100). When omitted, priorities are auto-assigned from list order (index × 10).
- **`is_entity_default`** boolean optional — Mark as the org's default rule. At most one entry may be `true`. Default: `false`.


## Returns

Returns the full updated stack as an array of stack items.

Request

```bash
curl -X PUT https://api.aitronos.com/v1/organizations/org_abc123/rules-stack \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {"rule_id": "rule_xyz", "priority": 0, "is_entity_default": true},
      {"rule_id": "rule_abc", "priority": 10}
    ]
  }'
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

result = client.org_rule_stack.replace(
    org_id="org_abc123",
    entries=[
        {"rule_id": "rule_xyz", "priority": 0, "is_entity_default": True},
        {"rule_id": "rule_abc", "priority": 10},
    ],
)
print(f"Stack now has {result.total} rules")
```


```python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
response = requests.put(
    "https://api.aitronos.com/v1/organizations/org_abc123/rules-stack",
    headers={"X-API-Key": api_key, "Content-Type": "application/json"},
    json={
        "entries": [
            {"rule_id": "rule_xyz", "priority": 0, "is_entity_default": True},
            {"rule_id": "rule_abc", "priority": 10},
        ]
    },
)
print(response.json())
```


```javascript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch(
  "https://api.aitronos.com/v1/organizations/org_abc123/rules-stack",
  {
    method: "PUT",
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      entries: [
        { rule_id: "rule_xyz", priority: 0, is_entity_default: true },
        { rule_id: "rule_abc", priority: 10 }
      ]
    })
  }
);

const data = await response.json();
console.log(data);
```

Response

```json
{
  "items": [
    {
      "attachment_id": "att_001",
      "rule_id": "rule_xyz",
      "name": "Professional Tone",
      "description": "Enforce professional language across all assistants",
      "scope": "organization",
      "priority": 0,
      "is_active": true,
      "is_entity_default": true,
      "organization_id": "org_abc123"
    },
    {
      "attachment_id": "att_002",
      "rule_id": "rule_abc",
      "name": "Concise Responses",
      "description": null,
      "scope": "organization",
      "priority": 10,
      "is_active": true,
      "is_entity_default": false,
      "organization_id": "org_abc123"
    }
  ],
  "total": 2
}
```

Error

```json
{
  "success": false,
  "error": {
    "code": "RULE_STACK_MULTIPLE_DEFAULTS",
    "message": "At most one stack entry may be marked as the default.",
    "type": "client_error",
    "status": 422,
    "details": {
      "default_count": 2
    },
    "trace_id": "abc123",
    "timestamp": "2025-01-15T10:00:00Z",
    "system_message": "Technical error detail for diagnostics"
  }
}
```

## Related Resources

- [List organisation rule stack](/docs/api-reference/rules/org-stack-list)
- [Add rule to organisation stack](/docs/api-reference/rules/org-stack-add)
- [Remove rule from organisation stack](/docs/api-reference/rules/org-stack-remove)