Skip to main content

​
Overview

The Catafract API provides endpoints for image generation, file uploads, project management, authentication, and payment processing. All API endpoints require authentication unless otherwise specified.

​
Base URL

http://localhost:3000/api
For production, replace with your deployment URL.

​
Authentication

All API endpoints use NextAuth.js for authentication with Google OAuth. Requests must include a valid session cookie obtained through the authentication flow.

​
Authentication Flow

  1. User visits /login
  2. Clicks “Sign in with Google”
  3. NextAuth redirects to Google OAuth
  4. Google redirects back to /api/auth/callback/google
  5. Session cookie is set automatically

​
Protected Routes

The following routes require authentication:
  • /api/image - AI image generation
  • /api/upload - File uploads
  • /api/user - User data
  • /api/user/project - Project management
  • /api/user/project/canvas - Canvas state management
  • /api/checkout - Payment checkout
  • /api/portal - Customer portal

​
Rate Limits

Currently, there are no explicit rate limits implemented. However, AI image generation is limited by:
  • Gemini API quotas
  • Azure Blob Storage limits
  • Session-based authentication

​
Error Responses

All endpoints return standard HTTP status codes:

​
Success Codes

  • 200 - Success
  • 201 - Created

​
Client Error Codes

  • 400 - Bad Request (missing or invalid parameters)
  • 401 - Unauthorized (no valid session)
  • 404 - Not Found

​
Server Error Codes

  • 500 - Internal Server Error
Error responses follow this format: 
{
  "error": "Error message",
  "details": "Additional error details (optional)"
}

​
Endpoints Overview

​
Image Generation

  • POST /api/image - Generate AI images using Gemini

​
File Management

  • POST /api/upload - Upload images to Azure Blob Storage

​
User Management

  • GET /api/user - Get current user data

​
Project Management

  • POST /api/user/project - Create a new project
  • GET /api/user/project - Get user’s projects

​
Canvas Management

  • POST /api/user/project/canvas - Save canvas state
  • GET /api/user/project/canvas - Load canvas state

​
Authentication

  • GET/POST /api/auth/[...nextauth] - NextAuth.js endpoints

​
Payments (Polar)

  • GET /api/checkout - Create checkout session
  • GET /api/portal - Access customer portal
  • POST /api/webhook/polar - Handle Polar webhooks

​
Video (Mux)

  • GET /api/mux/asset - Get Mux asset status

​
SDK and Tools

Currently, Catafract does not provide an official SDK. All endpoints can be accessed using standard HTTP clients like:
  • fetch (JavaScript/TypeScript)
  • axios
  • curl
  • Any HTTP client library

​
Next Steps

Image Generation

Generate AI images with Gemini

File Upload

Upload images to Azure

Projects

Manage projects and canvas

Authentication

Learn about authentication