# Tool Name: `site-create`

**Module**: Channels > Sites  
**Version**: 1.0.0  
**Status**: Stable

## Overview

Creates a new site in the Modyo platform with custom domain support. Sites are the top-level containers for pages, widgets, and templates in the Channels module.

## Use Cases

- Launch new website or web application
- Create staging environment for testing
- Set up brand-specific site in multi-tenant setup
- Deploy customer-facing portal with custom domain

## Parameters

### Required Parameters

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| platformSlug | string | Platform identifier from ~/.platforms.json | "production" |
| site.host | string | Domain name (must be valid hostname format) | "mysite.modyo.me" |
| site.name | string | Display name for the site | "My Website" |
| site.theme | string | Theme ID (currently only "208" supported) | "208" |

### Optional Parameters

| Parameter | Type | Default | Description | Example |
|-----------|------|---------|-------------|---------|
| site.realm_id | number\|null | null | Realm ID for customer authentication | 5 |
| site.description | string | "" | Site description for documentation | "Corporate website" |
| site.team_review | boolean | false | Enable team review workflow for changes | true |

## Response

### Success Response

```json
{
  "id": 123,
  "uuid": "abc-123-def-456",
  "name": "My Website",
  "host": "mysite.modyo.me",
  "status": 0,
  "language": "en",
  "time_zone": "UTC",
  "created_at": "2025-01-09T10:00:00Z",
  "updated_at": "2025-01-09T10:00:00Z",
  "base_url": "https://mysite.modyo.me",
  "base_admin_url": "https://account.modyo.com/admin/sites/123",
  "team_review": false,
  "realm_id": null,
  "stages_enabled": false,
  "public_css": "",
  "public_js": "",
  "editable_css": "",
  "editable_js": ""
}
```

### Error Responses

**422 Validation Error**
```json
{
  "error": "Validation failed",
  "details": {
    "host": ["has already been taken"]
  }
}
```

**400 Bad Request**
```json
{
  "error": "Invalid host format",
  "message": "Host must be a valid domain name"
}
```

## Examples

### Example 1: Basic Site Creation

Create a simple site with minimal configuration:

```json
{
  "platformSlug": "production",
  "site": {
    "host": "mysite.modyo.me",
    "name": "My New Site",
    "realm_id": null,
    "theme": "208"
  }
}
```

**Result**: Creates site accessible at `https://mysite.modyo.me`

### Example 2: Site with Authentication Realm

Create a site with customer login enabled:

```json
{
  "platformSlug": "production",
  "site": {
    "host": "customers.mycompany.com",
    "name": "Customer Portal",
    "realm_id": 5,
    "theme": "208"
  }
}
```

**Result**: Creates site where users can register/login using realm authentication.

### Example 3: Production Site with Team Review

Create a production site with approval workflow:

```json
{
  "platformSlug": "production",
  "site": {
    "host": "www.mycompany.com",
    "name": "Corporate Website",
    "realm_id": null,
    "theme": "208",
    "description": "Public-facing corporate website",
    "team_review": true
  }
}
```

**Result**: Creates site where all changes require team approval before publishing.

## Related Tools

- `site-get` - Retrieve site details after creation to verify configuration
- `site-list` - List all sites to confirm creation and get site ID
- `site-update` - Modify site settings after initial creation
- `site-delete` - Remove site when no longer needed
- `page-create` - Add pages to the newly created site
- `template-create` - Add templates and snippets to the site

## Common Patterns

### Pattern 1: Complete Site Setup Workflow

```
1. site-create → create site infrastructure
2. site-get → verify site created and get full details
3. template-create (type: "snippet") → add header snippet
4. template-create (type: "snippet") → add footer snippet  
5. template-create (type: "css") → add global styles
6. template-create (type: "js") → add global scripts
7. page-create (path: "/") → create home page
8. page-create (path: "/about") → create about page
9. site-list → verify complete setup
```

### Pattern 2: Clone Site for Different Environment

```
1. site-list (source) → get source site configuration
2. template-list-snippets (source) → get all snippets to replicate
3. site-create (new) → create new site with similar config
4. [For each snippet]: template-create (new) → recreate snippets
5. page-list (source) → get page structure
6. [For each page]: page-create (new) → recreate pages
```

### Pattern 3: Multi-Brand Site Creation

```
1. site-create (brand-a) → create first brand site
2. site-create (brand-b) → create second brand site
3. site-create (brand-c) → create third brand site
4. [For each site]: template-create → add brand-specific styles
5. [For each site]: global-variable-create → set brand colors/config
```

## Troubleshooting

### Issue: "Host has already been taken"

**Cause**: Another site in the platform is already using this domain name  
**Solution**: 
- Choose a different unique domain name
- Delete the existing site if it's no longer needed
- Use `site-list` to see all existing site domains

### Issue: "Invalid host format"

**Cause**: Domain doesn't match hostname validation regex  
**Solution**: Use valid hostname format:
- Lowercase only: `mysite.modyo.me` ✅ not `MySite.Modyo.me` ❌
- Alphanumeric with hyphens: `my-site.modyo.me` ✅
- No spaces or special characters: `my site.com` ❌
- Must have domain extension: `mysite` ❌ `mysite.com` ✅

### Issue: "Realm not found"

**Cause**: The realm_id doesn't exist in the platform  
**Solution**: 
- Use `realm-list` tool to get valid realm IDs
- Set `realm_id: null` if authentication is not needed
- Create realm first using `realm-create` if needed

### Issue: "Theme not found" or "Invalid theme"

**Cause**: Invalid theme ID provided  
**Solution**: Currently only theme "208" is supported in Modyo. Always use:
```json
"theme": "208"
```

### Issue: Site created but not accessible via URL

**Cause**: DNS not configured for custom domain  
**Solution**: 
- For `*.modyo.me` domains: Immediate DNS (no action needed)
- For custom domains: Configure DNS CNAME pointing to Modyo
- Wait for DNS propagation (can take up to 48 hours)

## Best Practices

1. **Use descriptive names** - Helps identify sites in admin UI and for team members
2. **Plan domain structure early** - Consider staging/production domain strategy
3. **Enable team_review for production** - Prevents accidental publishing of changes
4. **Document realm associations** - Keep track of which sites use authentication
5. **Follow naming conventions** - Use consistent naming across environments (e.g., `brand-staging`, `brand-production`)
6. **Test in staging first** - Create staging site before production site
7. **Use consistent theme** - Stick with theme "208" across all sites

## Permissions Required

- Valid Admin API access token in `~/.platforms.json`
- Channels module enabled in the Modyo platform
- Site creation permissions for the authenticated user
- Realm access (if associating with realm_id)

## Rate Limits

- **Standard**: 10 site creations per minute per platform
- **Platform limit**: May vary based on subscription plan
- **Concurrent requests**: Recommended max 5 simultaneous site creates

## Important Notes

- Site creation is **immediate** (no async processing required)
- Custom domains require **DNS configuration** outside of Modyo
- Theme selection is **limited to "208"** in current API version
- Site host **cannot be changed** after creation (requires site recreation)
- Deleted site domains become **available after 24 hours**
- Site creation does **not** create any default pages (use `page-create`)
- Empty sites show **404** until at least one page is published

## See Also

### Documentation
- [Channels Module Overview](../../guides/channels-overview.md)
- [Site Management Best Practices](../../guides/site-management.md)
- [Complete Site Setup Guide](../../guides/complete-site-setup.md)

### Official Modyo Documentation
- [Modyo Sites Official Docs](https://docs.modyo.com/en/platform/channels/sites.html)
- [API Reference](https://api.modyo.com/swagger#/sites/post_sites)
- [Custom Domain Configuration](https://docs.modyo.com/en/platform/channels/sites.html#custom-domains)

### Related Tool Documentation
- [site-update](./site-update.md) - Update site configuration
- [site-delete](./site-delete.md) - Delete sites
- [page-create](../pages/page-create.md) - Create pages in site
- [template-create](../templates/template-create.md) - Add templates to site