API Overview

Our API Philosophy

At Cüte, we prioritize developer experience and rapid iteration. Our architecture reflects this through a server-first approach that keeps our codebase simple and maintainable.

Current Architecture: Server Actions First

We currently build features using Next.js Server Actions as our primary data layer. This approach gives us:

Benefits

• Type-safe by default: End-to-end TypeScript from client to server
• Simplified auth: Authentication handled automatically through request context
• Faster development: No need to manage separate API routes for internal features
• Optimistic updates: Built-in support for progressive enhancement
• Zero latency: Server components can directly call database queries

When we use Server Actions

Server Actions power all our internal features:

• Item listing creation and updates
• User profile management
• Real-time chat messaging
• Search and filtering
• Authentication flows

Public API: In Development

We're actively building a public REST API to support our upcoming native mobile applications and third-party integrations.

Timeline

• Phase 1 (Current): Core endpoints for items management
• Phase 2 (Q1 2025): User authentication and profile management
• Phase 3 (Q2 2025): Search, messaging, and notifications
• Phase 4 (Q3 2025): Third-party developer access

API Design Principles

Our REST API follows modern best practices:

• RESTful conventions: Standard HTTP methods and status codes
• OpenAPI 3.0 spec: Fully documented with auto-generated SDKs
• Version control: /api/v1/* namespace for stable endpoints
• Type safety: Generated TypeScript types for all endpoints
• Rate limiting: Fair usage policies to ensure platform stability

Authentication

The public API will use:

• JWT tokens for stateless authentication
• API keys for server-to-server integrations
• OAuth 2.0 for third-party applications (Phase 4)

Available Endpoints

Current API endpoints are documented in the pages below. These endpoints are under active development and may change before general availability.

All endpoints require authentication and follow our standard response format:

{
  "data": T,           // Success response
  "error": string?,    // Error message if failed
  "meta": {
    "timestamp": string,
    "version": "v1"
  }
}

For Mobile Developers

If you're building a mobile app integration:

1. Contact us: Email dev@cüte.com for early access
2. Review the docs: Check endpoint references in the sidebar
3. Test in staging: We'll provide sandbox credentials
4. Stay updated: API changes will be communicated via changelog

Why Not API-First?

You might wonder why we didn't build APIs from day one. Here's our thinking:

Speed matters more than perfection.

Server Actions let us:

• Ship features in hours, not days
• Iterate based on user feedback
• Avoid premature optimization
• Keep our team small and focused

We're building the public API when we need it (mobile apps), not because it's architecturally "pure."

This pragmatic approach is core to how we work at Cüte.

Questions?

• Technical docs: See the endpoint references in the sidebar
• Integration help: dev@cüte.com
• Feature requests: GitHub Issues
• Status updates: Roadmap