# Main API Routes in the ACE-Step UI Backend: Complete Endpoint Reference > Explore the main API routes in the ACE-Step UI backend spanning authentication, user profiles, music generation & more. Master all ten REST endpoint groups implemented in Express. - Repository: [fspecii/ace-step-ui](https://github.com/fspecii/ace-step-ui) - Tags: api-reference - Published: 2026-04-29 --- **The ACE-Step UI backend exposes ten core REST endpoint groups under the `/api` prefix, including authentication, user profiles, song CRUD, playlists, AI music generation, and LoRA training pipelines, all implemented as Express routers in `server/src/routes/`.** The ACE-Step UI server is an Express application that organizes its HTTP API under the `/api` namespace. All route handlers live in the `server/src/routes/` directory and are mounted in [`server/src/index.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/index.ts). This architecture provides a clean separation between the web frontend and the backend services that manage the AI music generation workflows. ## Core API Endpoint Groups The backend groups functionality into distinct routers, each handling a specific domain of the music creation platform. ### Authentication (`/api/auth`) The authentication router in [`server/src/routes/auth.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/auth.ts) handles user identity and session management. It provides endpoints for automatic login detection, initial user setup, and JWT token generation. The `/api/auth/auto` endpoint returns the first available user and a valid JWT for rapid development setups, while `/api/auth/setup` accepts a username to create or retrieve a user profile. According to the source code in [`server/src/index.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/index.ts), this router mounts at `/api/auth` using `app.use('/api/auth', authRoutes)`. ### User Management (`/api/users`) User profiles and social features reside in [`server/src/routes/users.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/users.ts). This router supports public profile lookups via `/api/users/:username`, avatar and banner uploads through `/api/users/me/avatar` (using multipart/form-data), and creator following logic via `/api/users/:username/follow`. The `/api/users/public/featured` endpoint returns curated creators for the explore page, requiring no authentication via the `optionalAuthMiddleware`. ### Song Library (`/api/songs`) The song CRUD and streaming endpoints live in [`server/src/routes/songs.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/songs.ts). Authenticated users can list their creations at `/api/songs`, while public tracks are available at `/api/songs/public/:id`. The router handles audio proxying, like toggling via `/api/songs/:id/like`, and metadata management including title, lyrics, style tags, BPM, key signature, and duration. Songs integrate with the storage abstraction layer defined in [`server/src/services/storage/factory.js`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/services/storage/factory.js) for S3 or local file handling. ### Playlists (`/api/playlists`) Playlist management is centralized in [`server/src/routes/playlists.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/playlists.ts). Users create collections via POST to `/api/playlists` with JSON payloads containing name, description, and visibility flags. The router supports adding songs through `/api/playlists/:id/songs` and editing playlist metadata. Public discovery endpoints allow browsing of community-curated collections. ### Music Generation (`/api/generate`) The heart of the ACE-Step system resides in [`server/src/routes/generate.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/generate.ts). This router interfaces with the external ACE-Step service through [`server/src/services/acestep.js`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/services/acestep.js). Key endpoints include: - **POST `/api/generate`** – Submit music generation jobs with parameters like `songDescription`, `instrumental` flag, and duration - **GET `/api/generate/status/:localJobId`** – Poll for completion status - **POST `/api/generate/upload-audio`** – Upload reference audio files for conditioning - **GET `/api/generate/models`** – List available DiT model checkpoints - **GET `/api/generate/limits`** – Query GPU memory constraints and generation limits The service wrapper handles Python path resolution and status synchronization with the local SQLite database. ### Training and LoRA (`/api/training` and `/api/lora`) AI model fine-tuning capabilities split across two routers. [`server/src/routes/training.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/training.ts) manages audio dataset uploads, preprocessing via Python scripts, and LoRA training orchestration. The `/api/training/checkpoints` endpoint enumerates ACE-Step model checkpoints on disk, while `/api/training/lora-checkpoints` lists fine-tuned adaptations. The [`server/src/routes/lora.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/lora.ts) router provides utilities for model checkpoint listing, export operations, and LoRA-specific management tasks, supporting the custom model training workflow. ### Reference Tracks (`/api/reference-tracks`) Reference audio management for generation conditioning lives in [`server/src/routes/referenceTrack.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/referenceTrack.ts). These endpoints handle reference track uploads, metadata tagging, and association with generation jobs, enabling users to influence AI output style through existing audio examples. ### Contact and Support (`/api/contact`) The public contact form submission system exists in [`server/src/routes/contact.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/contact.ts). The POST `/api/contact` endpoint accepts name, email, subject, message, and category fields, storing submissions for admin review without requiring authentication. ## Route Registration in the Express Application In [`server/src/index.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/index.ts), the Express application imports and mounts all routers under the `/api` prefix using the following pattern: ```typescript import authRoutes from './routes/auth.js'; import songsRoutes from './routes/songs.js'; import generateRoutes from './routes/generate.js'; import usersRoutes from './routes/users.js'; import playlistsRoutes from './routes/playlists.js'; import contactRoutes from './routes/contact.js'; import referenceTrackRoutes from './routes/referenceTrack.js'; import loraRoutes from './routes/lora.js'; import trainingRoutes from './routes/training.js'; app.use('/api/auth', authRoutes); app.use('/api/songs', songsRoutes); app.use('/api/generate', generateRoutes); app.use('/api/users', usersRoutes); app.use('/api/playlists', playlistsRoutes); app.use('/api/contact', contactRoutes); app.use('/api/reference-tracks', referenceTrackRoutes); app.use('/api/lora', loraRoutes); app.use('/api/training', trainingRoutes); ``` Additional inline routes defined directly in [`server/src/index.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/index.ts) include `/api/oembed` for OpenGraph embed data, `/song/:id` for social media preview pages with HTML meta tags, and static asset servers mounted at `/audio/*`, `/editor/*`, and `/demucs-web/*` for audio files and web-based editing tools. ## Authentication Middleware All protected routes utilize JWT-based authentication middleware located in [`server/src/middleware/auth.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/middleware/auth.ts). The system provides three middleware variants: - **`authMiddleware`** – Requires valid JWT, returns 401 if missing - **`optionalAuthMiddleware`** – Attaches user context if token present, allows anonymous access - **`adminMiddleware`** – Restricts endpoints to users with administrative privileges Routes handling public resources like `/api/songs/public/:id` and `/api/users/public/featured` typically use `optionalAuthMiddleware` to support both authenticated and guest browsing. ## Practical API Usage Examples Below are runnable **cURL** commands demonstrating key interactions with the ACE-Step UI backend. Replace `localhost:3000` with your deployment host and include JWT tokens where indicated. ### Authenticate and Retrieve Tokens ```bash # Auto-login for development (returns first user + JWT) curl http://localhost:3000/api/auth/auto # Create or retrieve user by username curl -X POST http://localhost:3000/api/auth/setup \ -H "Content-Type: application/json" \ -d '{"username":"creator1"}' ``` ### Manage User Profiles ```bash # Fetch public profile (no authentication required) curl http://localhost:3000/api/users/creator1 # Upload avatar (requires JWT) curl -X POST http://localhost:3000/api/users/me/avatar \ -H "Authorization: Bearer $JWT" \ -F "avatar=@/path/to/image.png" # Follow another creator curl -X POST http://localhost:3000/api/users/creator2/follow \ -H "Authorization: Bearer $JWT" ``` ### Song Operations ```bash # List authenticated user's songs curl http://localhost:3000/api/songs \ -H "Authorization: Bearer $JWT" # Create a new song entry manually curl -X POST http://localhost:3000/api/songs \ -H "Authorization: Bearer $JWT" \ -H "Content-Type: application/json" \ -d '{ "title":"My AI Composition", "lyrics":"AI generated lyrics here", "style":"electronic", "duration":180, "bpm":128, "keyScale":"Am", "isPublic":true }' # Like a song curl -X POST http://localhost:3000/api/songs/12345/like \ -H "Authorization: Bearer $JWT" ``` ### Generate Music ```bash # Submit a generation job curl -X POST http://localhost:3000/api/generate \ -H "Authorization: Bearer $JWT" \ -H "Content-Type: application/json" \ -d '{ "customMode":false, "songDescription":"upbeat jazz fusion with saxophone", "instrumental":true, "duration":120 }' # Check generation status curl http://localhost:3000/api/generate/status/abc123 \ -H "Authorization: Bearer $JWT" # List available models curl http://localhost:3000/api/generate/models ``` ### Playlist Management ```bash # Create a playlist curl -X POST http://localhost:3000/api/playlists \ -H "Authorization: Bearer $JWT" \ -H "Content-Type: application/json" \ -d '{"name":"Chill Vibes","isPublic":true}' # Add song to playlist curl -X POST http://localhost:3000/api/playlists/9876/songs \ -H "Authorization: Bearer $JWT" \ -H "Content-Type: application/json" \ -d '{"songId":"12345"}' ``` ### Submit Contact Form ```bash curl -X POST http://localhost:3000/api/contact \ -H "Content-Type: application/json" \ -d '{ "name":"Support User", "email":"user@example.com", "subject":"Feature Request", "message":"Please add dark mode", "category":"feedback" }' ``` ## Summary - **Ten core endpoint groups** under `/api` handle authentication, users, songs, playlists, generation, training, LoRA, reference tracks, and contact forms, implemented as separate Express routers in `server/src/routes/`. - **JWT-based security** uses `authMiddleware`, `optionalAuthMiddleware`, and `adminMiddleware` from [`server/src/middleware/auth.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/middleware/auth.ts) to protect routes while allowing public browsing of shared content. - **Route mounting** occurs centrally in [`server/src/index.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/index.ts), which also defines inline routes for oEmbed data, social previews, and static asset serving. - **Music generation** (`/api/generate`) serves as the primary integration point with the ACE-Step inference engine, handling job submission, status polling, and model configuration. - **Training pipeline** (`/api/training` and `/api/lora`) provides complete workflows for dataset preparation and custom model fine-tuning through REST endpoints. ## Frequently Asked Questions ### What is the base URL prefix for all API endpoints in ACE-Step UI? All REST endpoints use the `/api` prefix. For example, authentication routes are accessed at `/api/auth/*`, song operations at `/api/songs/*`, and generation endpoints at `/api/generate/*`. This prefix is applied in [`server/src/index.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/index.ts) where each router mounts under `/api` followed by its specific path segment. ### Which endpoints require authentication versus allowing anonymous access? Endpoints under `/api/auth`, `/api/users/me/`, `/api/songs` (private listing), `/api/playlists` (creation), and `/api/generate` require valid JWT tokens via `authMiddleware`. However, public resources like `/api/songs/public/:id`, `/api/users/public/featured`, `/api/users/:username` (profiles), and `/api/contact` use `optionalAuthMiddleware`, allowing anonymous access while still recognizing logged-in users when tokens are present. ### How does the music generation endpoint interact with the AI backend? The `/api/generate` routes in [`server/src/routes/generate.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/generate.ts) act as a proxy to the external ACE-Step service defined in [`server/src/services/acestep.js`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/services/acestep.js). When a client POSTs to `/api/generate`, the server creates a database entry, forwards the request to the Python-based ACE-Step inference engine, and returns a `localJobId`. Clients poll `/api/generate/status/:localJobId` to track progress; upon completion, the system creates a permanent `songs` database record with the generated audio URL. ### Where are static assets and embedded previews served from? Static audio files, the AudioMass editor, and Demucs web UI are served from `/audio/*`, `/editor/*`, and `/demucs-web/*` respectively, configured in [`server/src/index.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/index.ts). Social media embeds use the `/song/:id` route (returning HTML with OpenGraph meta tags) and `/api/oembed` (returning JSON embed data), both defined inline in the main Express application file rather than in the separate route modules.