# Common API Quirks

Documented API behaviors and workarounds.

## ID vs UUID

| Field | Behavior |
|-------|----------|
| `id` | Changes after publishing (new version) |
| `uuid` | Stable across versions |

Always use UUID for stable references.

## Publishing Behavior

### Widget/Template IDs
- IDs change when published
- Refetch lists after publishing
- Use UUID for widget page references

### Widget Publishing Order
1. Create widget definition
2. **Publish widget** (required)
3. Add to page using `definition_uuid`

## Field Formats

### Content Groups (Nested Children)
```json
{
  "children": [
    { "parent_id": "temp_1", "name": "New Child" },
    { "parent_id": 123, "name": "Existing Child" }
  ]
}
```
- `parent_id: "temp_N"` for new items
- `parent_id: number` for existing items

### Asset Sources
Accept multiple formats:
- Manager URL: `/api/files/{id}`
- External URL: `https://...`
- Local path: `/path/to/file`

### Widget UUIDs
- 40-character hex OIDs
- NOT RFC 4122 UUIDs
- Example: `507f1f77bcf86cd799439011`

## Page Paths

### Home Page
- Path is `''` (empty string)
- NOT `/home` or `home`
- Cannot be deleted/unpublished

### Path Format
- No leading slash: `blog` not `/blog`
- Nested: `products/category`

## List vs Detail Responses

Some fields differ between list and detail:

### Pages
- List: `full_path`
- Detail: `path`

### Widgets
- List: `status: "published"` (string)
- Detail: `published: true` (boolean)

## Pagination Limits

| Default | Max |
|---------|-----|
| 30 | 100 |

## Template Names

Allowed characters:
- Lowercase letters (a-z)
- Numbers (0-9)
- Underscores (_)

**Invalid**: uppercase, hyphens, spaces