API Reference

Layout API

The Layout API provides endpoints for creating, reading, updating, and deleting venue seating layouts.

Base URL

All API endpoints are relative to your application's base URL:

https://your-domain.com/api

Authentication

API requests require authentication using Better Auth. Ensure users are signed in before making requests.

Endpoints

Get Layout

Retrieve a specific layout by ID.

GET /api/layouts/[id]

Parameters:

Parameter	Type	Required	Description
`id`	string	Yes	Layout unique ID

Response:

{
  "id": "uuid",
  "name": "Main Theater",
  "data": {
    "seats": [...],
    "rows": [...],
    "areas": [...],
    "sections": [...],
    "pricingCategories": [...]
  },
  "userId": "user-id",
  "organizationId": "org-id",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T12:00:00Z"
}

List Layouts

Get all layouts for the current user/organization.

GET /api/layouts

Query Parameters:

Parameter	Type	Required	Description
`organizationId`	string	No	Filter by organization
`limit`	number	No	Number of results (default 50)
`offset`	number	No	Pagination offset

Response:

{
  "layouts": [
    {
      "id": "uuid",
      "name": "Main Theater",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T12:00:00Z"
    }
  ],
  "total": 10
}

Create Layout

Create a new seating layout.

POST /api/layouts

Request Body:

{
  "name": "New Theater",
  "data": {
    "seats": [],
    "rows": [],
    "areas": [],
    "sections": [],
    "pricingCategories": []
  },
  "organizationId": "org-id" // Optional
}

Response:

{
  "id": "new-uuid",
  "name": "New Theater",
  "createdAt": "2025-01-15T14:00:00Z"
}

Update Layout

Update an existing layout.

PUT /api/layouts/[id]
PATCH /api/layouts/[id]

Request Body:

{
  "name": "Updated Name", // Optional
  "data": {
    // Updated layout data
  }
}

Response:

{
  "success": true,
  "updatedAt": "2025-01-15T15:00:00Z"
}

Delete Layout

Delete a layout.

DELETE /api/layouts/[id]

Response:

{
  "success": true
}

Set Pricing

Configure pricing for a layout.

POST /api/layouts/[id]/set-pricing

Request Body:

{
  "pricingCategories": [
    {
      "id": "adult",
      "name": "Adult",
      "price": 50,
      "color": "#3b82f6"
    },
    {
      "id": "child",
      "name": "Child",
      "price": 25,
      "color": "#10b981"
    }
  ]
}

Set Availability

Update seat/area availability.

POST /api/layouts/[id]/set-availability

Request Body:

{
  "seats": [
    {
      "id": "seat-1",
      "isAvailable": true
    }
  ],
  "areas": [
    {
      "id": "area-1",
      "availableCount": 100
    }
  ]
}

Data Models

Layout

interface Layout {
  id: string;
  name: string;
  seats: Seat[];
  rows: SeatRow[];
  areas?: Area[];
  sections: Section[];
  pricingCategories: PricingCategory[];
  createdAt: Date;
  updatedAt: Date;
}

Seat

interface Seat {
  id: string;
  rowId: string;
  indexInRow: number;
  row: string;
  number: string;
  pricingCategoryIds: string[];
  isAvailable?: boolean;
  isUnbookable?: boolean;
  isAccessible?: boolean;
  hasRestrictedView?: boolean;
}

SeatRow

interface SeatRow {
  id: string;
  startX: number;
  startY: number;
  endX: number;
  endY: number;
  label: string;
  seatCount: number;
  curve: number;
  sectionId?: string;
  pricingCategoryIds: string[];
}

Area

interface Area {
  id: string;
  name: string;
  purchaseType: 'multiple-customer' | 'single-customer';
  pricingMethod: 'per-person' | 'per-area';
  shape: 'rectangle' | 'circle' | 'polygon' | 'custom';
  pricingCategoryIds: string[];
  maxOccupancy: number;
  minOccupancy?: number;
}

PricingCategory

interface PricingCategory {
  id: string;
  name: string;
  price: number;
  color: string;
}

Error Responses

All errors follow this format:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "status": 400
}

Common error codes:

NOT_FOUND: Layout not found
UNAUTHORIZED: User not authenticated
FORBIDDEN: User doesn't have access to this layout
VALIDATION_ERROR: Invalid request data
SERVER_ERROR: Internal server error

Rate Limiting

API requests are rate-limited per user:

100 requests per minute for authenticated users
10 requests per minute for unauthenticated requests

API Reference

Layout API

Base URL

Authentication

Endpoints

Get Layout

List Layouts

Create Layout

Update Layout

Delete Layout

Set Pricing

Set Availability

Data Models

Layout

Seat

SeatRow

Area

PricingCategory

Error Responses

Rate Limiting

Next Steps

On this page