API Documentation

Build amazing puzzle applications with the Puzzlr API. Access puzzle data, user progress, reviews, and more through our RESTful API.

Quick Start Guide

1

Authentication Setup

Configure Clerk authentication for your application

import { ClerkProvider } from '@clerk/nextjs'

export default function App({ children }) {
  return (
    <ClerkProvider>
      {children}
    </ClerkProvider>
  )
}
2

Make API Calls

Use authenticated requests to access Puzzlr API

const response = await fetch('/api/puzzles', {
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  }
})

const puzzles = await response.json()
3

Handle Responses

Process API responses and handle errors

if (response.ok) {
  const data = await response.json()
  // Handle success
} else {
  const error = await response.json()
  console.error('API Error:', error.message)
}

API Reference

Authentication

Secure authentication endpoints using Clerk

GET/api/auth/user
Auth Required

Get current user information

POST/api/auth/sync
Auth Required

Sync user data with Supabase

Puzzles

Manage puzzle data and information

GET/api/puzzles

Get paginated list of approved puzzles

GET/api/puzzles/[id]

Get specific puzzle details

POST/api/puzzles
Auth Required

Create new puzzle entry

PUT/api/puzzles/[id]
Auth Required

Update puzzle information

Puzzle Logs

Track user puzzle progress and status

GET/api/puzzle-logs
Auth Required

Get user's puzzle logs

POST/api/puzzle-logs
Auth Required

Create new puzzle log entry

PUT/api/puzzle-logs/[id]
Auth Required

Update puzzle log status/notes

DELETE/api/puzzle-logs/[id]
Auth Required

Remove puzzle from user collection

Reviews

Puzzle reviews and ratings system

GET/api/reviews

Get reviews with filters

POST/api/reviews
Auth Required

Submit puzzle review

PUT/api/reviews/[id]
Auth Required

Update user's review

DELETE/api/reviews/[id]
Auth Required

Delete user's review

Collections

Puzzle collections and curation

GET/api/collections

Get public collections

POST/api/collections
Auth Required

Create new collection

GET/api/collections/[id]

Get collection details

POST/api/collections/[id]/follow
Auth Required

Follow/unfollow collection

Media Upload

Image upload and management

POST/api/upload-photos
Auth Required

Upload puzzle progress photos

DELETE/api/upload-photos/[id]
Auth Required

Delete uploaded photo

Authentication

Clerk Integration

Puzzlr uses Clerk for authentication. All authenticated requests require a valid Clerk session token.

// Get auth token in your frontend
import { useAuth } from '@clerk/nextjs'

const { getToken } = useAuth()
const token = await getToken()

// Include in API requests
fetch('/api/puzzle-logs', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

Base URL

All API requests should be made to:

https://puzzlr.in/api/

Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Error Response

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "details": {}
  }
}

Rate Limits & Guidelines

Rate Limits

  • • Authenticated requests: 1000 requests/hour
  • • Public endpoints: 100 requests/hour
  • • File uploads: 50 uploads/hour
  • • Bulk operations: 10 requests/minute

Best Practices

  • • Cache responses when possible
  • • Use pagination for large datasets
  • • Handle rate limit responses gracefully
  • • Respect data privacy and community guidelines

SDKs & Tools

JavaScript SDK

Official SDK for web applications

Coming Soon

Postman Collection

Ready-to-use API collection

Coming Soon

OpenAPI Spec

Machine-readable API specification

Coming Soon

These developer tools are currently in development.

Contact us for early access or specific API needs

Need Help with the API?

Our developer community and support team are here to help you build amazing puzzle applications.

Contact Developer Supportbusiness@puzzlr.in