Public API Reference

GammaCMS exposes a set of read-only REST endpoints that make it easy to ship headless experiences (marketing sites, booking portals, kiosks, etc.). This document focuses on the public API that is available to your hotel partners.

The admin API (/api/v1/...) documented elsewhere is still available for authenticated dashboard operations. The sections below cover the publicly consumable endpoints under /api/public/v1/.

Base URL

https://app.gammacms.com/api/public/v1/

You can also use your own domain (e.g. https://api.yourcms.com/api/public/v1/) once DNS is configured. All responses are JSON.

Authentication

Public requests use API keys instead of JWTs.

In the GammaCMS dashboard navigate to Dashboard → Settings → API Keys.
Create a key, set optional rate limits, and copy the generated token prefixed with pk_.
Include the key in every request using the X-API-Key header.
Supply an organization context so the API knows which tenant to serve:
- X-Organization-ID: <organization_uuid> – recommended for multi-org integrations.

Example request:

curl \
  -H "X-API-Key: pk_123456789" \
  -H "X-Organization-ID: ec9a9dcb-24d7-4074-9f5c-9c2fcee5c462" \
  "https://app.gammacms.com/api/public/v1/sites/?domain=hamptonbay.example"

If an API key is suspended, expired, or missing you will receive 401 Unauthorized.

Rate Limiting

Rate limits are enforced per API key using a sliding-window algorithm (Redis backed).

Bucket	Default	Headers exposed
Requests / minute	120	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`
Requests / day	10,000	same as above

You can override limits on a per-key basis in the dashboard.

Sites

List or retrieve information about published sites belonging to the authenticated organization.

List by domain

GET /sites/?domain={domain}

Query parameters

Name	Description
domain	(optional) filter by custom domain

Response

[
  {
    "id": "4f834b99-0b38-4a72-8d22-37ac0c62be0e",
    "name": "Hampton Bay Retreat",
    "slug": "hampton-bay-retreat",
    "description": "A coastal sanctuary for discerning travelers.",
    "domain": "hamptonbay.example",
    "meta_title": "Hampton Bay Retreat | Coastline Luxury",
    "meta_description": "Ocean-view suites, curated dining, and bespoke adventures along the Pacific.",
    "og_image_url": "https://cdn.gammacms.com/media/hamptonbay/og.jpg",
    "favicon_url": "https://cdn.gammacms.com/media/hamptonbay/favicon.ico",
    "settings": {
      "theme": "hotel-classic",
      "primary_color": "#1B3A57",
      "secondary_color": "#E9B44C",
      "font_family": "Playfair Display"
    },
    "published_at": "2025-02-10T08:15:00Z"
  }
]

Retrieve a site by domain

GET /sites/{domain}/

{
  "id": "4f834b99-0b38-4a72-8d22-37ac0c62be0e",
  "name": "Hampton Bay Retreat",
  "slug": "hampton-bay-retreat",
  "description": "A coastal sanctuary for discerning travelers.",
  "domain": "hamptonbay.example",
  "meta_title": "Hampton Bay Retreat | Coastline Luxury",
  "meta_description": "Ocean-view suites, curated dining, and bespoke adventures along the Pacific.",
  "og_image_url": "https://cdn.gammacms.com/media/hamptonbay/og.jpg",
  "favicon_url": "https://cdn.gammacms.com/media/hamptonbay/favicon.ico",
  "settings": {
    "theme": "hotel-classic",
    "primary_color": "#1B3A57",
    "secondary_color": "#E9B44C",
    "font_family": "Playfair Display",
    "navigation": []
  },
  "published_at": "2025-02-10T08:15:00Z"
}

Pages

Pages expose both rich-text (content) and section-based layout (sections). Only published pages (status = published and published_at ≤ now) are returned.

List pages for a site

GET /sites/{domain}/pages/

Query parameters

Name	Description
parent	(optional) filter by parent page UUID
order_by	(optional) default `-published_at`

Response (truncated)

[
  {
    "id": "3a2278e4-8b01-45d1-b3b7-f558f74cdef4",
    "title": "Rooms & Suites",
    "slug": "rooms-and-suites",
    "excerpt": "Ocean-view suites and private villas.",
    "featured_image_url": null,
    "meta_title": "Rooms & Suites | Hampton Bay Retreat",
    "meta_description": "Oceanfront suites, residential-style villas, bespoke amenities.",
    "og_image_url": "https://cdn.gammacms.com/media/hamptonbay/rooms.jpg",
    "og_type": "article",
    "status": "published",
    "published_at": "2025-02-10T09:00:00Z",
    "layout": "default",
    "is_homepage": false,
    "author": {
      "id": "c7a5dcf8-6f69-4d43-90c4-9d83c6cabb41",
      "name": "Ava Mitchell"
    },
    "site": {
      "id": "4f834b99-0b38-4a72-8d22-37ac0c62be0e",
      "name": "Hampton Bay Retreat",
      "domain": "hamptonbay.example"
    }
  }
]

Retrieve a page

GET /sites/{domain}/pages/{slug}/

{
  "id": "3a2278e4-8b01-45d1-b3b7-f558f74cdef4",
  "title": "Rooms & Suites",
  "slug": "rooms-and-suites",
  "excerpt": "Ocean-view suites and private villas.",
  "featured_image_url": null,
  "meta_title": "Rooms & Suites | Hampton Bay Retreat",
  "meta_description": "Oceanfront suites, residential-style villas, bespoke amenities.",
  "og_image_url": "https://cdn.gammacms.com/media/hamptonbay/rooms.jpg",
  "og_type": "article",
  "status": "published",
  "published_at": "2025-02-10T09:00:00Z",
  "layout": "default",
  "is_homepage": false,
  "author": {
    "id": "c7a5dcf8-6f69-4d43-90c4-9d83c6cabb41",
    "name": "Ava Mitchell"
  },
  "site": {
    "id": "4f834b99-0b38-4a72-8d22-37ac0c62be0e",
    "name": "Hampton Bay Retreat",
    "domain": "hamptonbay.example"
  },
  "content_mode": "sections",
  "content": {
    "root": {
      "type": "root",
      "version": 1,
      "children": [
        /* Lexical JSON for rich text */
      ]
    }
  },
  "sections": [
    {
      "id": "dfdc6f9c-5ab2-4d88-92a6-564d5c5ee0de",
      "type": "content",
      "layout": "container",
      "background": "white",
      "padding": "large",
      "blocks": [
        {
          "id": "a0f326b3-7883-4b86-8681-f4f3c3f4631a",
          "type": "text",
          "content": {
            "root": {
              "type": "root",
              "version": 1,
              "children": [
                /* Lexical JSON */
              ]
            }
          },
          "settings": {}
        }
      ]
    }
  ]
}

Menus

Menus provide hierarchical navigation structures (header, footer, sidebar, etc.).

GET /sites/{domain}/menus/
GET /sites/{domain}/menus/{location}/

Locations include header, footer, sidebar, mobile, and custom.

Sample response:

[
  {
    "id": "64bd9f8f-1c4d-4a2a-9f87-0f13b6227f0f",
    "name": "Main Navigation",
    "location": "header",
    "is_active": true,
    "items": [
      {
        "id": "f984a0d1-1688-4b0e-b353-48350df78358",
        "label": "Home",
        "url": "/",
        "target": "_self",
        "page": {
          "id": "9d8d1a5c-1f6b-4438-a081-adf47136a61a",
          "title": "Home",
          "slug": "home"
        }
      }
    ]
  }
]

Categories & Tags

Use categories/tags to power blogs, events, or itinerary listings.

GET /sites/{domain}/categories/
GET /sites/{domain}/categories/{slug}/
GET /sites/{domain}/categories/{slug}/pages/
GET /sites/{domain}/tags/

Each category response includes slug, icon, color, parent, and optional page counts. The /pages/ sub-route returns serialized pages identical to the Pages endpoint.

Media

Media endpoints provide URLs, alt text, and file metadata for assets that belong to the organization.

GET /sites/{domain}/media/
GET /sites/{domain}/media/{id}/

Query parameters

Name	Description
type	Filter by `image`, `video`, `audio`, `document`

Response example

{
  "id": "cba6e485-f61c-4d00-9644-7fa96ee3f9bf",
  "title": "Ocean Terrace",
  "file_name": "ocean-terrace.jpg",
  "file_url": "https://cdn.gammacms.com/media/hamptonbay/ocean-terrace.jpg",
  "file_type": "image",
  "file_size": 2845320,
  "mime_type": "image/jpeg",
  "width": 2400,
  "height": 1350,
  "alt_text": "Guests enjoying sunset cocktails on the ocean terrace",
  "caption": "Sunset cocktails on the terrace",
  "created_at": "2025-01-17T21:14:02Z"
}

Tip: combine media metadata with landing-page sections to render hero images and galleries.

Rooms

Rooms expose published room types for a site, including amenities, seasonal rates, and gallery images. Only rooms with status = published are returned, ordered by order then name.

List rooms for a site

GET /sites/{domain}/rooms/

Response (truncated)

[
  {
    "id": "b8e1c3a7-5d9f-4e2b-a1c6-8f3d7e9b0a24",
    "name": "Ocean View Suite",
    "slug": "ocean-view-suite",
    "short_description": "Spacious suite with panoramic ocean views and private balcony.",
    "max_guests": 2,
    "bed_type": "King",
    "size": "450 sq ft",
    "featured_image_url": "https://cdn.gammacms.com/media/hamptonbay/ocean-view-suite.jpg",
    "is_featured": true,
    "order": 1
  }
]

Retrieve a room

GET /sites/{domain}/rooms/{slug}/

Returns all list fields plus full description, images, custom fields, nested amenities, and seasonal rates.

{
  "id": "b8e1c3a7-5d9f-4e2b-a1c6-8f3d7e9b0a24",
  "name": "Ocean View Suite",
  "slug": "ocean-view-suite",
  "short_description": "Spacious suite with panoramic ocean views and private balcony.",
  "description": "Wake up to the sound of waves in our signature Ocean View Suite. Floor-to-ceiling windows frame the Pacific coastline, while a private balcony invites sunset cocktails.",
  "max_guests": 2,
  "bed_type": "King",
  "size": "450 sq ft",
  "featured_image_url": "https://cdn.gammacms.com/media/hamptonbay/ocean-view-suite.jpg",
  "is_featured": true,
  "order": 1,
  "images": [
    {
      "id": "cba6e485-f61c-4d00-9644-7fa96ee3f9bf",
      "file_url": "https://cdn.gammacms.com/media/hamptonbay/ocean-view-suite.jpg",
      "alt_text": "Ocean View Suite bedroom with king bed"
    }
  ],
  "custom_fields": {},
  "meta_title": "Ocean View Suite | Hampton Bay Retreat",
  "meta_description": "Book our signature Ocean View Suite with panoramic views and private balcony.",
  "amenities": [
    {
      "id": "a3f9d1e7-2c4b-4a8e-b5d6-1e7f9a3c5b80",
      "name": "Free Wi-Fi",
      "slug": "free-wi-fi",
      "icon": "wifi",
      "description": "Complimentary high-speed wireless internet."
    }
  ],
  "rates": [
    {
      "id": "d7c2e8f4-6a1b-4d3e-9f5a-2b8c4e6d0a19",
      "season_name": "Winter",
      "start_date": "2025-12-01",
      "end_date": "2026-03-31",
      "single_rate": "350.00",
      "double_rate": "425.00",
      "currency": "USD"
    }
  ]
}

Note: The amenities array only includes active amenities. The rates array only includes active rates.

Amenities

Amenities represent features available at the property or within specific rooms (e.g. Wi-Fi, pool, spa). Only amenities with is_active = true are returned, ordered by order then name.

List amenities for a site

GET /sites/{domain}/amenities/

Response

[
  {
    "id": "a3f9d1e7-2c4b-4a8e-b5d6-1e7f9a3c5b80",
    "name": "Free Wi-Fi",
    "slug": "free-wi-fi",
    "icon": "wifi",
    "description": "Complimentary high-speed wireless internet."
  }
]

Retrieve an amenity

GET /sites/{domain}/amenities/{slug}/

Returns all list fields plus custom fields.

{
  "id": "a3f9d1e7-2c4b-4a8e-b5d6-1e7f9a3c5b80",
  "name": "Free Wi-Fi",
  "slug": "free-wi-fi",
  "icon": "wifi",
  "description": "Complimentary high-speed wireless internet.",
  "custom_fields": {}
}

Testimonials

Testimonials surface guest reviews and endorsements. Only testimonials with is_active = true are returned, ordered by order then most recent (-created_at).

List testimonials for a site

GET /sites/{domain}/testimonials/

Response

[
  {
    "id": "e5a8b2c1-9d4f-4e7a-b3c6-7f1d2e8a0b59",
    "name": "Sarah Mitchell",
    "location": "New York, NY",
    "text": "An unforgettable stay. The ocean suite was breathtaking and the staff went above and beyond.",
    "rating": 5,
    "image_url": "https://cdn.gammacms.com/media/hamptonbay/guest-sarah.jpg",
    "is_featured": true
  }
]

Retrieve a testimonial

GET /sites/{domain}/testimonials/{id}/

Returns the same fields as the list response.

{
  "id": "e5a8b2c1-9d4f-4e7a-b3c6-7f1d2e8a0b59",
  "name": "Sarah Mitchell",
  "location": "New York, NY",
  "text": "An unforgettable stay. The ocean suite was breathtaking and the staff went above and beyond.",
  "rating": 5,
  "image_url": "https://cdn.gammacms.com/media/hamptonbay/guest-sarah.jpg",
  "is_featured": true
}

Note: The {id} parameter for testimonial detail is a UUID, not a slug.

Error Handling

Status	Meaning	Common causes
400	Bad Request	Invalid query parameter
401	Unauthorized	Missing/invalid API key
403	Forbidden	Key does not belong to organization
404	Not Found	Site/domain/page does not exist
429	Too Many Requests	Rate limit exceeded

When a rate limit is reached, check the Retry-After header for the number of seconds to wait before retrying.

Changelog

2025-02-10 – Initial release of public API, Lexical content support, section-based pages, global site seeding.
2025-02-20 – Added organization header requirement and improved rate-limit headers.
2026-02-26 – Added Rooms, Amenities, and Testimonials public API endpoints.

Need help or missing an endpoint? Reach out to support@gammacms.com with your use case.

Deployment Headless Integration