> ## Documentation Index
> Fetch the complete documentation index at: https://devkit4ai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud API Explained

> Understand the hosted backend API that powers authentication, projects, and AI generation.

The Cloud API is a production-ready backend service that provides all the server-side functionality for your AI applications.

**Production Servers:**

* **[api.devkit4ai.com](https://api.devkit4ai.com)** — Primary production server
* **[api.vibecoding.ad](https://api.vibecoding.ad)** — Alternative production server

Both servers provide identical functionality. Your [Starter Kit](/getting-started/starter-kit-explained) connects to one of these servers based on your environment configuration.

## What It Provides

### Authentication Services

* **User registration:** Create new user accounts with email and password
* **Login/logout:** Secure authentication with JWT tokens
* **Token refresh:** Automatic token renewal for continuous sessions
* **Email verification:** Verify user email addresses
* **Password reset:** Secure password recovery flow
* **Session management:** Handle user sessions across devices

### Project Management

* **Project CRUD:** Create, read, update, and delete projects
* **API key generation:** Create project-scoped authentication keys
* **Key management:** List, revoke, and track API key usage
* **Project isolation:** Multi-tenant architecture ensures data separation

### AI Generation

* **Image generation:** Create AI images using Replicate models
* **Status tracking:** Monitor generation progress and completion
* **History management:** Access past generations for authenticated users
* **Public sharing:** Toggle image visibility for sharing
* **Anonymous generation:** Support for unauthenticated generation flows

### Health & Monitoring

* **Health checks:** Verify API availability and status
* **Database status:** Check backend database connectivity
* **Storage status:** Verify file storage availability
* **Detailed diagnostics:** Get comprehensive system information

## How Authentication Works

### JWT Token Flow

<Steps>
  <Step title="User logs in">
    Starter Kit sends email/password to `/api/v1/auth/login`
  </Step>

  <Step title="API validates credentials">
    Cloud API checks credentials and generates tokens
  </Step>

  <Step title="Tokens returned">
    Access token (30 min) and refresh token (7 days) sent to client
  </Step>

  <Step title="Tokens stored">
    Starter Kit stores tokens in httpOnly cookies for security
  </Step>

  <Step title="Authenticated requests">
    Subsequent requests include JWT token automatically
  </Step>
</Steps>

### Required Headers

All API requests from your Starter Kit include these authentication headers:

* **X-User-Role:** Identifies the user type (end\_user for Starter Kit users)
* **X-Developer-Key:** Your developer credential from Cloud Admin
* **X-Project-ID:** Your project's unique identifier (UUID format)
* **X-API-Key:** Your project's API key
* **Authorization:** JWT token for authenticated user requests

### Role-Based Access

Different [user types](/getting-started/user-types) have different access levels to API endpoints:

| Endpoint Group     | Operator | Developer      | End User         |
| ------------------ | -------- | -------------- | ---------------- |
| Health Check       | ✅        | ✅              | ✅                |
| Authentication     | ✅        | ✅              | ✅                |
| Project Management | ✅        | ✅ Own projects | ❌                |
| AI Generation      | ✅        | ✅              | ✅ Project-scoped |

<Tip>
  Learn more about each user type and their capabilities in the [User Types](/getting-started/user-types) guide.
</Tip>

## API Endpoints

The Cloud API is organized into logical groups:

### Health Check Endpoints

* `GET /health` - Quick health status
* [`GET /api/v1/health`](/cloud-api/health/check) - Comprehensive health check
* [`GET /api/v1/health/database`](/cloud-api/health/database) - Database connectivity
* [`GET /api/v1/health/storage`](/cloud-api/health/storage) - File storage status
* [`GET /api/v1/health/redis`](/cloud-api/health/redis) - Cache status (if configured)

### Authentication Endpoints

* [`POST /api/v1/auth/register`](/cloud-api/auth/register) - Create new user
* [`POST /api/v1/auth/login`](/cloud-api/auth/login) - Authenticate user
* [`GET /api/v1/auth/me`](/cloud-api/auth/me) - Get current user info
* [`POST /api/v1/auth/refresh`](/cloud-api/auth/refresh) - Refresh access token
* [`POST /api/v1/auth/verify-email`](/cloud-api/auth/verify-email) - Verify email address
* [`POST /api/v1/auth/request-verification`](/cloud-api/auth/request-verification) - Request verification email

### Project Endpoints

* [`GET /api/v1/projects`](/cloud-api/projects/list) - List user's projects
* [`POST /api/v1/projects`](/cloud-api/projects/create) - Create new project
* [`GET /api/v1/projects/{id}`](/cloud-api/projects/get) - Get project details
* [`DELETE /api/v1/projects/{id}`](/cloud-api/projects/delete) - Delete project
* [`POST /api/v1/projects/{id}/api-keys`](/cloud-api/projects/create-api-key) - Generate API key
* [`GET /api/v1/projects/{id}/api-keys`](/cloud-api/projects/list-api-keys) - List project keys
* [`DELETE /api/v1/projects/{id}/api-keys/{key_id}`](/cloud-api/projects/revoke-api-key) - Revoke key

### Generation Endpoints

* [`POST /api/v1/generation/generate-v2`](/cloud-api/generation/create) - Create AI generation
* [`GET /api/v1/generation/{id}/status`](/cloud-api/generation/status) - Check generation status
* [`GET /api/v1/generation`](/cloud-api/generation/list) - List user's generations
* [`PATCH /api/v1/generation/{id}/public`](/cloud-api/generation/toggle-public) - Toggle visibility
* [`DELETE /api/v1/generation/{id}`](/cloud-api/generation/delete) - Delete generation
* [`GET /api/v1/generation/public`](/cloud-api/generation/public-list) - List public generations

## Integration with Starter Kit

The Starter Kit is pre-configured to work with the Cloud API:

1. **Environment variables** set the API URL and credentials
2. **Deployment mode** validates configuration on startup
3. **Server actions** in `app/actions.ts` call API endpoints
4. **Authentication context** manages user state from API responses
5. **Headers automatically included** in all requests

## Rate Limits & Quotas

<Info>
  Rate limits and quotas depend on your plan. Contact support for details about upgrading or custom limits.
</Info>

## API Documentation

For detailed endpoint documentation, request/response examples, and parameter descriptions, see the [Cloud API Reference](/cloud-api/introduction) section.

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/cloud-api/introduction">
    Explore detailed endpoint documentation
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/starter-kit/auth/jwt-flow">
    Learn about JWT authentication flow
  </Card>

  <Card title="API Integration" icon="plug" href="/starter-kit/advanced/api-integration">
    Advanced API integration patterns
  </Card>

  <Card title="Health Checks" icon="heart-pulse" href="/cloud-api/health/check">
    Monitor API availability
  </Card>
</CardGroup>