# List categories

div
strong
🔨 In Development
 — This section is still being developed and may change.


Retrieve the list of available rule categories for your organization, including recommended character limits and priority ranges for each category.

This endpoint returns the categories configured for your organization. Categories can be customized per organization and include recommended limits for optimal rule performance. Use this to understand available categories before creating rules.

#### Path Parameters

**`organizationId`** string required

The organization identifier whose rule categories should be returned.

#### Query Parameters

**`include_categories`** boolean optional · Defaults to `false`

Include the default system categories (`safety`, `professional`, `creative`, `technical`, `formatting`, `compliance`) in addition to organization-specific categories.

**`active_only`** boolean optional · Defaults to `true`

Only return categories that are actively used by existing rules in your organization.

## Returns

A [RulesResponse](#rulesresponse) object containing the API response data.

List organization categories

```bash
curl "https://api.freddy.aitronos.com/v1/organizations/org_123/rules/categories?include_categories=true" \
-H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests

organization_id = "org_123"

response = requests.get(
  f"https://api.freddy.aitronos.com/v1/organizations/{organization_id}/rules/categories",
  headers={
      "Authorization": f"Bearer {api_key}"
  },
  params={
      "include_categories": True
  }
)

categories = response.json()["data"]
print(f"Available categories: {[cat['name'] for cat in categories]}")
for cat in categories:
  print(f"{cat['name']}: {cat['recommendedLimit']} chars (priority {cat['priorityRange']})")
```


```javascript
const response = await fetch(`https://api.freddy.aitronos.com/v1/organizations/${organizationId}/rules/categories?include_categories=true`, {
headers: {
  'Authorization': `Bearer ${apiKey}`
}
});

const { data: categories } = await response.json();
console.log(`Available categories: ${categories.map(cat => cat.name).join(', ')}`);
categories.forEach(cat => {
console.log(`${cat.name}: ${cat.recommendedLimit} chars (priority ${cat.priorityRange})`);
});
```

Active categories only

```bash
curl "https://api.freddy.aitronos.com/v1/organizations/org_123/rules/categories?active_only=true" \
-H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests

organization_id = "org_123"

response = requests.get(
  f"https://api.freddy.aitronos.com/v1/organizations/{organization_id}/rules/categories",
  headers={
      "Authorization": f"Bearer {api_key}"
  },
  params={
      "active_only": True
  }
)

categories = response.json()["data"]
print(f"Active categories ({len(categories)}):")
for cat in categories:
  print(f"  - {cat['name']} ({cat['usageCount']} rules)")
```


```javascript
const response = await fetch(`https://api.freddy.aitronos.com/v1/organizations/${organizationId}/rules/categories?active_only=true`, {
headers: {
  'Authorization': `Bearer ${apiKey}`
}
});

const { data: categories } = await response.json();
console.log(`Active categories (${categories.length}):`);
categories.forEach(cat => {
console.log(`  - ${cat.name} (${cat.usageCount} rules)`);
});
```

## Response

200 OK

```json
{
  "object": "list",
  "data": [
    {
      "name": "safety",
      "description": "Critical safety and compliance rules with highest priority",
      "recommended_limit": 5000,
      "priority_range": "90-100",
      "usage_count": 12,
      "is_default": true,
      "is_active": true,
      "max_length": 50000,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-10-01T12:00:00Z"
    },
    {
      "name": "professional",
      "description": "Business communication standards with high priority",
      "recommended_limit": 4000,
      "priority_range": "70-89",
      "usage_count": 8,
      "is_default": true,
      "is_active": true,
      "max_length": 50000,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-10-01T12:00:00Z"
    },
    {
      "name": "creative",
      "description": "Creative writing guidelines with medium priority",
      "recommended_limit": 3000,
      "priority_range": "50-69",
      "usage_count": 5,
      "is_default": true,
      "is_active": true,
      "max_length": 50000,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-10-01T12:00:00Z"
    },
    {
      "name": "engineering_docs",
      "description": "Engineering documentation standards",
      "recommended_limit": 2500,
      "priority_range": "40-59",
      "usage_count": 3,
      "is_default": false,
      "is_active": true,
      "max_length": 50000,
      "createdAt": "2024-09-15T10:30:00Z",
      "updatedAt": "2024-09-15T10:30:00Z"
    }
  ],
  "total_count": 4,
  "has_more": false
}
```

Errors

```json
{
"error": {
  "type": "authentication_error",
  "message": "Invalid API key",
  "code": "invalid_api_key"
}
}
```

### Category Object Properties

**`name`** string
Unique identifier for the category (lowercase, no spaces).

**`description`** string
Human-readable description of the category's purpose.

**`recommended_limit`** integer
Recommended maximum characters for rules in this category.

**`priority_range`** string
Recommended priority range for this category (format: "min-max").

**`usage_count`** integer
Number of active rules using this category.

**`is_default`** boolean
Whether this is a system default category.

**`is_active`** boolean
Whether this category is actively used by any rules.

**`max_length`** integer
Technical maximum length for rules in this category (always 50,000).

**`createdAt`** string · Format: ISO 8601
When the category configuration was created.

**`updatedAt`** string · Format: ISO 8601
When the category configuration was last updated.

## Usage Notes

### Organization Customization

Each organization can define custom categories beyond the default system categories:

- **Default categories** are always available: `safety`, `professional`, `creative`, `technical`, `formatting`, `compliance`
- **Custom categories** can be added by organization administrators with specific priority ranges and limits
- Use `include_categories=false` to see only your organization's custom categories


### Priority and Limits

The `priorityRange` and `recommendedLimit` help ensure optimal rule performance:

- **Higher priority categories** (90-100) get more context budget for critical rules
- **Lower priority categories** (30-49) should use concise rules to fit within budget constraints
- Exceeding recommended limits may cause automatic compression during rule application


### Best Practices

1. **Use existing categories** when possible to maintain consistency
2. **Create custom categories** for organization-specific needs (e.g., "legal_review", "brand_voice")
3. **Respect recommended limits** to ensure reliable rule application
4. **Review usage counts** to identify popular vs. underused categories
5. **Update category descriptions** to help team members understand their purpose


### Category Management

Organization administrators can:

- Add new custom categories via the Freddy Hub
- Modify recommended limits and priority ranges
- Archive unused categories (they remain available for existing rules)
- Set organization-wide defaults for new categories