Cuppa Docs

API Reference

The MyCuppa Content API provides access to news articles, learning resources, component catalog, and development resources.

Base URLs

  • Production: https://api.mycuppa.io
  • Development: http://localhost:3000/api

Authentication

Currently, the API is publicly accessible. Authentication will be added for premium endpoints.

// Future: Authentication header
headers: {
  'Authorization': 'Bearer YOUR_API_TOKEN'
}

Endpoints

Navigation

GET /navigation/manifest

Get the complete navigation structure for the application.

Query Parameters:

| Parameter | Type | Description | Default | |-----------|------|-------------|---------| | platform | string | Platform filter (ios, android, web) | web | | locale | string | Locale code (e.g., en, es) | en |

Example Request:

curl https://mycuppa.io/api/navigation/manifest?platform=ios

Example Response:

{
  "version": "1.0.0",
  "updated_at": "2025-11-14T00:00:00Z",
  "sections": [
    {
      "id": "home",
      "path": "/home",
      "title": "Home",
      "subtitle": "Landing & Overview",
      "icon": "house.fill",
      "color": "#8B4513",
      "accessLevel": "public",
      "priority": 1,
      "metadata": {
        "searchable": true,
        "keywords": ["home", "landing", "start"],
        "tags": ["navigation", "main"]
      }
    }
  ]
}

Response Codes:

  • 200 OK - Manifest returned successfully
  • 304 Not Modified - Content unchanged (when using ETag)
  • 400 Bad Request - Invalid parameters
  • 500 Internal Server Error - Server error

ETag Support:

The endpoint supports ETags for efficient caching:

# Initial request
curl -i https://mycuppa.io/api/navigation/manifest
# Returns: ETag: "abc123"

# Subsequent request
curl -H 'If-None-Match: "abc123"' https://mycuppa.io/api/navigation/manifest
# Returns: 304 Not Modified (if content unchanged)

News

GET /news/articles

Retrieve a paginated list of published news articles.

Query Parameters:

| Parameter | Type | Description | Default | |-----------|------|-------------|---------| | category | string | Filter by category | - | | featured | boolean | Filter featured articles | false | | limit | integer | Number of articles (1-100) | 20 | | offset | integer | Pagination offset | 0 |

Categories:

  • ai - Artificial Intelligence
  • frameworks - Development Frameworks
  • tools - Development Tools
  • industry - Industry News
  • research - Research & Papers
  • projects - Community Projects
  • mobile-ios - iOS Development
  • mobile-android - Android Development
  • web - Web Development

Example Request:

curl "https://api.mycuppa.io/news/articles?category=ai&limit=10"

Example Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Building AI Agents with Claude",
    "slug": "building-ai-agents-with-claude",
    "excerpt": "Learn how to build intelligent agents...",
    "content": "Full article content...",
    "category": "ai",
    "tags": ["ai", "claude", "agents"],
    "author": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "publishedAt": "2025-11-14T10:00:00Z",
    "updatedAt": "2025-11-14T10:00:00Z",
    "featured": true,
    "imageUrl": "https://cdn.mycuppa.io/images/article.jpg"
  }
]

GET /news/articles/:slug

Retrieve a specific article by its URL slug.

Path Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | slug | string | Article URL slug |

Example Request:

curl https://api.mycuppa.io/news/articles/building-ai-agents-with-claude

Response Codes:

  • 200 OK - Article found
  • 404 Not Found - Article does not exist
  • 500 Internal Server Error - Server error

Learning

GET /learning/tutorials

Get a list of learning tutorials and resources.

Query Parameters:

| Parameter | Type | Description | Default | |-----------|------|-------------|---------| | category | string | Filter by category | - | | difficulty | string | Filter by difficulty level | - | | limit | integer | Number of tutorials | 20 | | offset | integer | Pagination offset | 0 |

Difficulty Levels:

  • beginner
  • intermediate
  • advanced

Example Request:

curl "https://api.mycuppa.io/learning/tutorials?difficulty=beginner&limit=5"

Example Response:

[
  {
    "id": "tutorial-001",
    "title": "Getting Started with SwiftUI",
    "slug": "getting-started-swiftui",
    "description": "Learn the basics of SwiftUI...",
    "category": "mobile-ios",
    "difficulty": "beginner",
    "duration": "30 minutes",
    "publishedAt": "2025-11-01T00:00:00Z",
    "author": {
      "name": "Jane Smith",
      "avatar": "https://cdn.mycuppa.io/avatars/jane.jpg"
    }
  }
]

Components

GET /components

Get the component library catalog.

Query Parameters:

| Parameter | Type | Description | Default | |-----------|------|-------------|---------| | platform | string | Platform filter | - | | category | string | Component category | - |

Platforms:

  • ios
  • android
  • web

Example Request:

curl "https://api.mycuppa.io/components?platform=ios&category=buttons"

Example Response:

[
  {
    "id": "primary-button",
    "name": "PrimaryButton",
    "category": "buttons",
    "platform": "ios",
    "description": "A primary button component",
    "props": [
      {
        "name": "title",
        "type": "String",
        "required": true,
        "description": "Button title text"
      },
      {
        "name": "action",
        "type": "() -> Void",
        "required": true,
        "description": "Button tap handler"
      }
    ],
    "example": "PrimaryButton(title: \"Submit\") { ... }"
  }
]

Data Models

NavigationItem

interface NavigationItem {
  id: string;
  path: string;
  title: string;
  subtitle?: string;
  icon?: string;
  color?: string;
  accessLevel: 'public' | 'authenticated' | 'premium' | 'admin';
  priority: number;
  metadata?: NavigationMetadata;
  children?: NavigationItem[];
}

interface NavigationMetadata {
  searchable: boolean;
  keywords: string[];
  tags: string[];
  description?: string;
}

NewsArticle

interface NewsArticle {
  id: string;
  title: string;
  slug: string;
  excerpt: string;
  content: string;
  category: string;
  tags: string[];
  author: Author;
  publishedAt: string;
  updatedAt: string;
  featured: boolean;
  imageUrl?: string;
}

interface Author {
  name: string;
  email?: string;
  avatar?: string;
}

Tutorial

interface Tutorial {
  id: string;
  title: string;
  slug: string;
  description: string;
  category: string;
  difficulty: 'beginner' | 'intermediate' | 'advanced';
  duration: string;
  publishedAt: string;
  author: Author;
}

Error Responses

All endpoints use consistent error response format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid category parameter",
    "details": {
      "parameter": "category",
      "validValues": ["ai", "frameworks", "tools"]
    }
  }
}

Common Error Codes:

| Code | Description | |------|-------------| | INVALID_PARAMETER | Request parameter is invalid | | NOT_FOUND | Resource not found | | UNAUTHORIZED | Authentication required | | FORBIDDEN | Access denied | | RATE_LIMIT_EXCEEDED | Too many requests | | INTERNAL_ERROR | Server error |

Rate Limiting

API requests are rate limited to prevent abuse:

  • Anonymous: 100 requests/minute
  • Authenticated: 1000 requests/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699876543

Pagination

Endpoints that return lists support pagination:

GET /news/articles?limit=20&offset=40

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 40,
    "hasMore": true
  }
}

Caching

HTTP Caching

API responses include cache headers:

Cache-Control: public, max-age=3600
ETag: "abc123"
Last-Modified: Wed, 14 Nov 2025 10:00:00 GMT

Client-Side Caching

Recommended client-side caching strategy:

  1. Short-lived cache (5 minutes) for frequently changing content
  2. Long-lived cache (1 hour) for stable content like navigation
  3. ETag validation for efficient updates
  4. Stale-while-revalidate for better UX

CORS

The API supports CORS for web applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

Versioning

The API is currently at version 1.0. Future breaking changes will introduce new versions:

https://api.mycuppa.io/v2/news/articles

Current endpoints without version prefix are v1.

SDKs

Official SDKs are available:

iOS (Swift)

import CuppaNavigation

let loader = EnhancedManifestLoader(
    apiURL: URL(string: "https://mycuppa.io/api/navigation/manifest")!
)
let manifest = try await loader.load()

TypeScript

import { fetchManifest } from '@mycuppa/api-client'

const manifest = await fetchManifest({
  platform: 'web',
  locale: 'en'
})

Support

OpenAPI Specification

Full OpenAPI 3.0 specification available at:

Found an issue with this page? Report it on GitHub