Skip to main content
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: 
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: 
{
  "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): 
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: 
{
  "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: 
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: 
{
  "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"
}
Full API keys are only shown once during creation. Store them securely.

​
Generation model

Represents an AI generation request: 
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: 
{
  "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: 
interface TokenResponse {
  access_token: string    // Short-lived JWT (30 min)
  refresh_token?: string  // Long-lived token (7 days)
  token_type: string      // "Bearer"
}
Example: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}
Tokens are automatically stored in httpOnly cookies by the Starter Kit auth system.

​
Error responses

All API errors follow this structure: 
interface ErrorResponse {
  detail: string          // Human-readable error message
}
Example: 
{
  "detail": "Invalid credentials"
}

​
TypeScript types

Define these types in your application:
lib/types/api.ts
// 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

components/project-card.tsx
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: 
interface PaginatedResponse<T> {
  items: T[]
  total: number
  page: number
  page_size: number
  has_more: boolean
}
Usage: 
const response = await fetch(
  `${apiUrl}/api/v1/generations/list?page=1&page_size=20`
)
const data: PaginatedResponse<Generation> = await response.json()

​
Next steps

API Reference

Complete endpoint documentation

Authentication

Auth flow details