Data Models

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()

User model

Project model

API Key model

Generation model

Auth tokens

Error responses

TypeScript types

Using types in components

Next steps

API Reference

Authentication

​User model

​Project model

​API Key model

​Generation model

​Auth tokens

​Error responses

​TypeScript types

​Using types in components

​Pagination

​Next steps

API Reference

Authentication

User model

Project model

API Key model

Generation model

Auth tokens

Error responses

TypeScript types

Using types in components

Pagination

Next steps