API Documentation

interface ContentItem {
  id: string;                          // UUID
  tenant_id: string;                   // UUID of the tenant
  content_type: string;                // 'project' | 'blog' | 'event' | 'book' | 'page'
  title: string;                       // Display title
  slug: string;                        // URL-safe identifier
  subtitle: string | null;             // Optional subtitle
  description: string | null;          // Short description/excerpt
  content_body: string | null;         // Full HTML content
  featured_image: string | null;       // URL to main image
  status: 'draft' | 'published' | 'archived';
  date_published: string | null;       // ISO 8601 timestamp
  event_date: string | null;           // For events - UTC ISO 8601
  event_timezone: string | null;       // For events - IANA timezone
  sort_order: number;                  // Display order (higher = first)
  tags: string[] | null;               // Array of tag strings
  core_attributes: Record<string, any>;
  custom_attributes: Record<string, any>;
  project_link: string | null;         // External project URL
  purchase_link: string | null;        // Buy/purchase URL
  series_id: string | null;            // UUID of parent series
  series_number: number | null;        // Order within series
  location: string | null;             // For events - location
  meta_title: string | null;           // SEO title
  meta_description: string | null;     // SEO description
  created_at: string;                  // ISO 8601 timestamp
  updated_at: string;                  // ISO 8601 timestamp
}

interface ContentMedia {
  id: string;                          // UUID
  content_id: string;                  // UUID of parent content item
  tenant_id: string;                   // UUID of tenant
  media_type: string;                  // 'image' | 'video' | 'document'
  url: string;                         // Public URL to media file
  alt_text: string | null;             // Accessibility text
  size_bytes: number | null;           // File size
  metadata: Record<string, any>;       // Additional metadata
  sort_order: number;                  // Display order
  created_at: string;                  // ISO 8601 timestamp
}

// List response with pagination
interface ContentListResponse {
  success: true;
  data: {
    items: ContentItem[];
    pagination: {
      limit: number;
      offset: number;
      total: number;
    };
  };
}

// Single item response (includes media)
interface ContentItemResponse {
  success: true;
  data: ContentItem & {
    media: ContentMedia[];
  };
}

// Error response
interface ErrorResponse {
  success: false;
  error: string;
  code?: string;
  details?: string;
}

const API_KEY = process.env.CMS_API_KEY; // Server-side only!
const BASE_URL = 'https://thedigitalfair.com/api/v1';

async function fetchProjects() {
  const response = await fetch(
    `${BASE_URL}/content?api_key=${API_KEY}&type=project&status=published`
  );

  if (!response.ok) {
    throw new Error(`API Error: ${response.status}`);
  }

  const data = await response.json();

  if (!data.success) {
    throw new Error('Failed to fetch projects');
  }

  return data.data.items;
}

// Usage
const projects = await fetchProjects();
projects.forEach(project => {
  console.log(`${project.title}: ${project.description}`);
});

// app/portfolio/page.tsx
import { Metadata } from 'next';

const API_KEY = process.env.CMS_API_KEY!; // Server-side only
const BASE_URL = 'https://thedigitalfair.com/api/v1';

async function getProjects() {
  const response = await fetch(
    `${BASE_URL}/content?api_key=${API_KEY}&type=project&status=published`,
    { next: { revalidate: 60 } } // Revalidate every 60 seconds
  );

  if (!response.ok) {
    throw new Error('Failed to fetch projects');
  }

  const data = await response.json();
  return data.data.items;
}

export default async function PortfolioPage() {
  const projects = await getProjects();

  return (
    <main className="container mx-auto py-12">
      <h1 className="text-4xl font-bold mb-8">Portfolio</h1>
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
        {projects.map((project) => (
          <a key={project.id} href={`/portfolio/${project.slug}`}>
            {project.featured_image && (
              <img
                src={project.featured_image}
                alt={project.title}
                className="w-full aspect-video object-cover rounded-lg"
              />
            )}
            <h2 className="text-xl font-semibold mt-4">{project.title}</h2>
            <p className="text-gray-600 mt-2">{project.description}</p>
          </a>
        ))}
      </div>
    </main>
  );
}

import requests
from typing import List, Dict, Any

API_KEY = "your-api-key"
BASE_URL = "https://thedigitalfair.com/api/v1"

def fetch_projects(
    content_type: str = "project",
    status: str = "published",
    limit: int = 50,
    offset: int = 0
) -> List[Dict[str, Any]]:
    """Fetch content items from The Digital Fair CMS."""

    params = {
        "api_key": API_KEY,
        "type": content_type,
        "status": status,
        "limit": limit,
        "offset": offset
    }

    response = requests.get(f"{BASE_URL}/content", params=params)
    response.raise_for_status()

    data = response.json()

    if not data.get("success"):
        raise Exception("API request failed")

    return data["data"]["items"]

# Usage
if __name__ == "__main__":
    projects = fetch_projects()
    for project in projects:
        print(f"- {project['title']} ({project['slug']})"

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": "Additional details (optional)"
}

async function fetchWithErrorHandling(endpoint: string) {
  try {
    const response = await fetch(`${BASE_URL}${endpoint}?api_key=${API_KEY}`);

    if (!response.ok) {
      const errorData = await response.json();

      switch (response.status) {
        case 401:
          throw new Error('Invalid API key. Please check your credentials.');
        case 404:
          if (errorData.code === 'NOT_CONFIGURED') {
            throw new Error('This feature has not been set up yet.');
          }
          if (errorData.code === 'NOT_PUBLISHED') {
            throw new Error('This content is not publicly available.');
          }
          throw new Error('The requested resource was not found.');
        case 500:
          throw new Error('Server error. Please try again later.');
        default:
          throw new Error(errorData.error || 'An unknown error occurred.');
      }
    }

    return await response.json();
  } catch (error) {
    if (error instanceof TypeError) {
      throw new Error('Network error. Please check your connection.');
    }
    throw error;
  }
}