> ## 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.

# Data Models

> Understand the data structures returned by the Cloud API.

The Cloud API returns structured data that your Starter Kit application consumes. Understanding these data models helps you build effective UI and business logic.

## User model

Represents an authenticated user:

```typescript theme={null}
interface User {
  id: string              // UUID
  email: string           // User's email address
  role: 'end_user'       // Always 'end_user' for Starter Kit
  is_active: boolean     // Account activation status
  created_at: string     // ISO 8601 timestamp
}
```

**Example:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "role": "end_user",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}
```

## Project model

Represents a project (when using developer endpoints):

```typescript theme={null}
interface Project {
  id: string              // UUID
  name: string            // Project name
  description: string | null
  is_active: boolean      // Project status
  created_at: string      // ISO 8601 timestamp
  updated_at: string | null
}
```

**Example:**

```json theme={null}
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "My AI App",
  "description": "AI-powered analytics platform",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}
```

## API Key model

Represents a project API key:

```typescript theme={null}
interface ApiKey {
  id: string              // UUID
  key_prefix: string      // First 8 chars for identification
  name: string | null     // Optional key name/description
  created_at: string      // ISO 8601 timestamp
  last_used_at: string | null  // Last usage timestamp
}
```

**Example:**

```json theme={null}
{
  "id": "8f2e7890-1234-5678-90ab-cdef12345678",
  "key_prefix": "pk_abcd1",
  "name": "Production API Key",
  "created_at": "2024-01-15T10:30:00Z",
  "last_used_at": "2024-01-25T09:15:00Z"
}
```

<Warning>
  Full API keys are only shown once during creation. Store them securely.
</Warning>

## Generation model

Represents an AI generation request:

```typescript theme={null}
interface Generation {
  id: string              // UUID
  user_id: string         // Creator's user ID
  instructions: string    // Generation prompt
  status: 'pending' | 'processing' | 'completed' | 'failed'
  is_public: boolean      // Visibility setting
  generated_image_url: string | null  // Result URL
  created_at: string      // ISO 8601 timestamp
  completed_at: string | null
}
```

**Example:**

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "A futuristic cityscape at sunset",
  "status": "completed",
  "is_public": true,
  "generated_image_url": "https://storage.example.com/generations/image.jpg",
  "created_at": "2024-01-25T10:00:00Z",
  "completed_at": "2024-01-25T10:02:30Z"
}
```

## Auth tokens

JWT tokens returned during authentication:

```typescript theme={null}
interface TokenResponse {
  access_token: string    // Short-lived JWT (30 min)
  refresh_token?: string  // Long-lived token (7 days)
  token_type: string      // "Bearer"
}
```

**Example:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}
```

<Info>
  Tokens are automatically stored in httpOnly cookies by the Starter Kit auth system.
</Info>

## Error responses

All API errors follow this structure:

```typescript theme={null}
interface ErrorResponse {
  detail: string          // Human-readable error message
}
```

**Example:**

```json theme={null}
{
  "detail": "Invalid credentials"
}
```

## TypeScript types

Define these types in your application:

```typescript lib/types/api.ts theme={null}
// User types
export interface User {
  id: string
  email: string
  role: 'end_user'
  is_active: boolean
  created_at: string
}

// Project types
export interface Project {
  id: string
  name: string
  description: string | null
  is_active: boolean
  created_at: string
  updated_at: string | null
}

// Generation types
export interface Generation {
  id: string
  user_id: string
  instructions: string
  status: 'pending' | 'processing' | 'completed' | 'failed'
  is_public: boolean
  generated_image_url: string | null
  created_at: string
  completed_at: string | null
}

// API response types
export interface ApiResponse<T> {
  data?: T
  error?: string
}
```

## Using types in components

```tsx components/project-card.tsx theme={null}
import { Project } from '@/lib/types/api'

interface ProjectCardProps {
  project: Project
}

export function ProjectCard({ project }: ProjectCardProps) {
  return (
    <div>
      <h3>{project.name}</h3>
      <p>{project.description}</p>
      <time>{new Date(project.created_at).toLocaleDateString()}</time>
    </div>
  )
}
```

## Pagination

List endpoints support pagination:

```typescript theme={null}
interface PaginatedResponse<T> {
  items: T[]
  total: number
  page: number
  page_size: number
  has_more: boolean
}
```

**Usage:**

```tsx theme={null}
const response = await fetch(
  `${apiUrl}/api/v1/generations/list?page=1&page_size=20`
)
const data: PaginatedResponse<Generation> = await response.json()
```

## Next steps

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

  <Card title="Authentication" icon="key" href="/cloud-api/auth/login">
    Auth flow details
  </Card>
</CardGroup>