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
}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "[email protected]",
"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
}
{
"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
}
{
"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
}
{
"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"
}
{
"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
}
{
"detail": "Invalid credentials"
}
TypeScript types
Define these types in your application:
// 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>
)
}
interface PaginatedResponse<T> {
items: T[]
total: number
page: number
page_size: number
has_more: boolean
}
const response = await fetch(
`${apiUrl}/api/v1/generations/list?page=1&page_size=20`
)
const data: PaginatedResponse<Generation> = await response.json()
Next steps
