The Setup API manages the critical initialization phase of SveltyCMS. It handles database configuration, system seeding, and the creation of the primary administrative account.

---

⚡ Quick Reference

Feature	HTTP Endpoint	Method	Permission Required
Status Check	/api/setup/status	GET	Public (always)
Test Connection	/api/setup/test-db	POST	Pre-setup only
Seed Database	/api/setup/seed-db	POST	Pre-setup only
Complete Setup	/api/setup/complete	POST	Pre-setup only
Reinitialize	/api/setup/reinitialize	POST	manage:system (gated)

Security Gating: All endpoints except status are protected by isSetupComplete(). After setup finishes, /api/setup/test-db, /api/setup/seed-db, /api/setup/complete, and /api/setup/reinitialize all return 403 SETUP_ALREADY_COMPLETE. This is enforced at two levels: the handleSetupRoutes handler entry check, and the handle-system-state.ts middleware. See Server Hooks.

---

1. The Goal

Safely transition a fresh SveltyCMS installation from an unconfigured state to a production-ready environment by establishing a database connection and provisioning the first user.

---

2. The Solution

Pre-flight Verification

Before persisting the configuration, the system validates the provided database credentials.

Endpoint: POST /api/setup/test-db Payload:

{
  "type": "mongodb",
  "host": "localhost",
  "port": 27017,
  "database": "sveltycms",
  "username": "...",
  "password": "...",
  "directConnection": true
}
```

### Schema Provisioning

Triggers the creation of system collections, default roles, and internal configuration entries.

**Endpoint**: `POST /api/setup/seed-db`

### Finalization

The setup process concludes by creating the admin user and establishing their first session. Once successful, the system is marked as `ready`, and all setup endpoints (except `status`) are strictly blocked with 403.

---

## 3. The Mechanics

### Pre-Boot Architecture

The `setup.ts` handler operates in a standalone mode, allowing it to function before the primary database adapter and middleware are fully initialized.

```
sequenceDiagram
    participant User as Admin Wizard
    participant API as Setup Handler
    participant FS as config/private.ts
    participant DB as Database Engine

    User->>API: POST /seed-db
    API->>FS: writePrivateConfig()
    API->>DB: Build Collections & Roles
    API-->>User: 200 OK (Seeding Started)
```

---

## Related Documents

- [Installation Guide](/docs/getting-started)
- [System Reference (system.ts)](/docs/reference/api/system)
- [Authentication & Identity (auth.ts)](/docs/reference/api/auth)
- [Server Hooks Architecture](/docs/reference/architecture/server-hooks)